--inherited-members option

Author: michaliskambi

src/AdvancedFeatures.asciidoc

@@ -1,18 +1,46 @@
 :doctitle: Advanced Features
+:sectnums:
+:toc: left
+:toclevels: 4
 
-Summary of the most important non-obvious PasDoc features:
+Some important non-obvious PasDoc features:
+
+== Input
+
+* link:AutoAbstractOption[--auto-abstract] command-line option allows you to automatically treat the 1st sentence of the description as an abstract.
+
+* You can write entire pages using pasdoc syntax, with all supported link:SupportedTags[@tags]. This way you can use pasdoc like a simple document creation tool. See the link:IntroductionAndConclusion[Introduction and conclusion] documentation.
+
+* By default documentation is read from the source code comments. But you can also write it in separate external files: see the link:ReadDescriptionFromFile[--description] command-line option.
+
+* By default we consider only comments in the `interface` section of the unit. But you can enable parsing also the `implementation` sections, and using comments from it, using the link:ImplementationCommentsOption[--implementation-comments] option.
+
+* By default every comment before an identifier is treated as a documentation. But you can limit this with arbitrary link:CommentMarker[comment markers].
+
+* link:AutoLinkOption[--auto-link] command-line option allows you to avoid writing so many `@link` tags. Identifiers will be automatically turned into links.
+
+* link:MarkdownOption[Markdown support for emphasis, lists, code blocks etc.]
+
+== Output
+
+* Our HTML output has a https://github.com/pasdoc/pasdoc/discussions/230[modern, mobile-friendly design based on Bootstrap]. You can customize it using link:CssOption[--css or --css-based-on-bootstrap] command-line options. You can also add your own HTML code to the output using link:HtmlHeadBodyBeginEndOptions[--html-head, --html-body-begin and --html-body-end] command-line options.
+
+* The documentation of each class can also include link:InheritedMembersOption[inherited members].
+
+* The documentation of each class can have toggable (using checkboxes in HTML) visibility e.g. for protected members. See link:VisibleMembers[--visible-members] command-line option.
+
+* The documentation can point to the source code (file, line number) where given item is declared. It can even link to the online repository (e.g. GitHub) which is a great way to link people from your docs to your code. See the link:SourcePosition[--show-source-position, --source-url-pattern, --source-root] command-line options.
 
-* The documentation can be written in an external files (see the link:ReadDescriptionFromFile[--description] command-line option), not only in the source code.
-* The documentation comments in the source code may be in the `interface` or (if you use link:ImplementationCommentsOption[--implementation-comments] option) `implementation` section of the unit.
-* The documentation can be localized to many languages, see the link:OutputLanguage[--language] command-line option.
-* Support for arbitrary (even optional) link:CommentMarker[comment markers].
-* You can write entire pages using pasdoc syntax (like @-tags, see link:WritingDocumentation[WritingDocumentation]). This way you can use pasdoc like a simple document creation tool. See the link:IntroductionAndConclusion[IntroductionAndConclusion] documentation.
 * You can easily add a search box to your documentation, just pass link:UseTipueSearchOption[--use-tipue-search] command-line option.
+
+* The documentation can be localized to many languages, see the link:OutputLanguage[--language] command-line option.
+
 * link:GraphVizSupport[GraphVizSupport] allows PasDoc to easily incorporate classes inheritance and unit dependency graphs in the documentation.
-* link:AutoLinkOption[--auto-link] command-line option allows you to avoid writing @link tags, identifiers will be automatically turned into links.
-* link:AutoAbstractOption[--auto-abstract] command-line option allows you to automatically treat the 1st sentence of the description as an abstract.
+
 * link:SpellChecking[Spell checking].
+
+== More
+
 * link:CacheOption[Caching for faster generation of documentation].
-* link:MarkdownOption[Markdown support for emphasis, lists, code blocks etc.]
 
-If you want to compare link:index[PasDoc] to FpDoc (another open-source Pascal documentation tool), see link:PasDocFpDocComparison[PasDocFpDocComparison] .
+* See also link:PasDocFpDocComparison[comparison of PasDoc with FpDoc (another open-source Pascal documentation tool)].

src/CommandLine.asciidoc

@@ -33,6 +33,9 @@ Read description from this file
 link:IncludeInSearchPath[-I, --include]::
 Include search path
 
+link:InheritedMembersOption[--inherited-members]::
+Include inherited members in the documentation of a class.
+
 -S, --source::
 Read source filenames from file, - (single dash) means standard input.
 

src/InheritedMembersOption.asciidoc

@@ -0,0 +1,50 @@
+:doctitle: --inherited-members command-line option
+:sectnums:
+:toc: left
+:toclevels: 4
+
+## Introduction
+
+Use the command-line option `--inherited-members` to include inherited members in the documentation of a class. This allows to see, at a glance, all members of a given class -- both defined in the given class and inherited from its ancestors.
+
+This feature is only meaningful for the link:HtmlOutput[HTML output format] right now. The inherited members, if requested, are present in the generated output and user has a checkbox (using JavaScript) to show / hide them.
+
+The _"members"_ means all the things declared in a class:
+
+- fields
+- properties
+- methods
+- constants
+- types, including nested classes.
+
+## Example
+
+```pascal
+type
+  TBase = class
+    procedure BaseMethod;
+  end;
+
+  TDerived = class(TBase)
+    procedure DerivedMethod;
+  end;
+```
+
+By default, documentation of `TDerived` will include only `DerivedMethod`. Use `--inherited-members=default-show` or `--inherited-members=default-hide` to include `BaseMethod` in the documentation of `TDerived`. This reflects the typical usage: if you have an instance of `TDerived`, you can call both `DerivedMethod` and `BaseMethod` on it, so it's useful to have documentation showing both methods on the same page.
+
+## Possible values of --inherited-members
+
+--inherited-members=never::
+  Do not include inherited members in the documentation of a class. This is the default behavior.
+
+--inherited-members=default-show::
+  Include inherited members in the documentation of a class. Inherited members are shown by default. User can hide them using a checkbox.
+
+--inherited-members=default-hide::
+  Include inherited members in the documentation of a class, however they are hidden by default. User can show them using a checkbox.
+
+## Default value and future plans
+
+The `never` remains the default for now, but it may change in the future. We recommend to test your documentation with `--inherited-members=default-hide` and let us know how do you like it (https://github.com/pasdoc/pasdoc/discussions/[e.g. in this discussion thread]).
+
+In our experience, practically the only drawback of using `--inherited-members=default-hide` (versus leaving the default `never`) is that it makes generating HTML documentation a bit slower (as we necessarily generate more content, duplicating a lot of the descriptions). That said, it's not a big difference. For https://castle-engine.io/apidoc/html/index.html[Castle Game Engine API docs], time of generation grew from 1:30 to 2:40 -- not really noticeable, esp. since documentation is updated by CI, so it doesn't really matter that it now takes almost 3 minutes. Again, let us know https://github.com/pasdoc/pasdoc/discussions/[your experience with this option].

src/_Sidebar.asciidoc

@@ -70,6 +70,7 @@ link:CommandLine[Command Line]: ::
 * link:HtmlHeadBodyBeginEndOptions[--html-head, --html-body-begin, --html-body-end]
 * link:IgnoreLeadingOption[--ignore-leading]
 * link:IgnoreMarkerOption[--ignore-marker]
+* link:InheritedMembersOption[--inherited-members]
 * link:IntroductionAndConclusion[--introduction, --conclusion, -A, --additional]
 * link:ImplicitVisibilityOption[--implicit-visibility]
 * link:TrueFalseNilTag[--lowercase-keywords]

src/_includes/sidebar.md

@@ -125,6 +125,8 @@
 
 * [\--ignore-marker](IgnoreMarkerOption)
 
+* [\--inherited-members](InheritedMembersOption)
+
 * [\--introduction, \--conclusion, -A, \--additional](IntroductionAndConclusion)
 
 * [\--implicit-visibility](ImplicitVisibilityOption)