WantedFeaturesParsingImplementation

Michalis Kamburelis edited this page Jan 8, 2017 · 9 revisions

Parsing implementation section

Currently, PasDoc only parses the interface section of a unit. Only the identifiers found in the interface section are documented, using only the comments in the interface section. For some people, this is OK, as the interface seems a right place to document things --- but it’s definitely a matter of taste.

Many people would like to parse also the implementation section of a unit, and get comments from there:

  • To document things visible in the interface by the comments from the implementation section. This is useful if you want to keep the interface section short, and you simply prefer to put (long) comments in the implementation section.

  • Or to document everything, not only things visible in the interface. This is useful if you want a documentation of unit internals. Closely related to this is the idea to parse a program file (which is very similar to the unit implementation).

This is a common PasDoc feature request (e.g. RFE 1189121, JavaDoc-like Tag handling, RFE 976519, 4 question…​). And we very much would like to have the option to parse implementation section! However, as far as we know, noone is actively working on it. We are waiting for YOUR patches!:) Please grab the latest PasDoc sources from GitHub https://github.com/pasdoc/pasdoc/ and submit patches or pull requests implementing it.

Implementing this is a matter of:

  • Adding to parser (PasDoc_Parser.pas) ability to parse implementation sections of units/programs. The parser needs not be a real parser — it can cheat by simply skipping some things without really understanding them (e.g. if you find a token begin then parser can simply consume tokens up to a matching end, without paying any attention to what it reads). So, keep hacking PasDoc_Parser.pas until it can parse the implementation section of your units.

  • This cannot break existing pasdoc working, so this feature should be only activated by a command-line option, like --parse-implementation. You can add two versions: --parse-implementation=only-for-interface and --parse-implementation=all, it looks like both approaches have their needs.

  • Decide how to merge documentation between interface/implementation (comments from the interface override comments from the implementation? The other way around? Maybe they should be glued together?)

If you would like to volunteer to implement this, please speak up on our mailing list (subscribe to pasdoc-main mailing list, see pasdoc-main archive).

For some older comments see also the thread Parsing of the implementation section of our mailing list.

PasDoc, documentation generator for Pascal:
Features:
Supported Tags:
Command Line:
Development:
Developers pages:
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.