PasDoc 0.16.0 release

[michalis]

We're proud to release PasDoc 0.16.0, a Pascal documentation generator. It's a big release gathering lots of small and large features we made in the last ~3 years

Detailed list of changes:

• New website (by Michalis)
• Moved everything to GitHub
• Ancestors list is now affected by external class hierarchy (by Michalis)
• Markdown support (by Fr0sT-Brutal)
• @note and @warning tags (by Bi0T1N)
• @url tag (by Bi0T1N)
• Allow to lowercase output of @nil, @false, @true by --lowercase-keywords (by Bi0T1N)
• Automatically detect flag like [xxx] at @param description. See here for example. (by PifPof)
• Scan implementation section of a unit in addition to the interface section (by Fr0sT-Brutal)
• Parser improvements to correctly handle some special cases: reading chars > $FF, "*.inc" includes, files with Mac-style line endings (by Fr0sT-Brutal)
• Mem leaks fixed (by Fr0sT-Brutal)
• Tag parameters now could be multiline without enclosing parens by means of "line feed" character "" (by Fr0sT-Brutal)
• Read additional command-line options from file (by Fr0sT-Brutal)
• --auto-back-comments command-line option (by Fr0sT-Brutal)
• pasdoc_gui opens a file given at command-line, opening WWW browser is optional (by Fr0sT-Brutal)
• @longCode without markers fixed (by Michalis)
• Support for namespaces in units in @links (by Fr0sT-Brutal)
• --ignore-marker option (by Fr0sT-Brutal)
• Test suite fixes and better documentation, in particular for Windows users
• Catalan translation updated (by Xavier Martínez)
• Delphi Tokyo files, to compile all projects and packages (by Carlos Feitoza Filho)
• Brazilian Portuguese translation updated (by Carlos Feitoza Filho)
• Parse identifiers declared as &xxx, where "xxx" may be a reserved word.
• Possibility to specify additional files using -A or --additional (by Alex Merkel)
• Added de.utf8 (German with UTF-8 encoding)
• Automatically remove %region and %endregion from comments
• Show visibility (public, protected, private...) inside records too (it is meanigful for advanced records)
• Implement in pasdoc_gui options to (by Michalis)
• customize HTML head and body
• set external descriptions file
• configure identifiers excluded from auto-linking
• Rename "internal" to "nested" to describe this language feature.
• The automatic tests are now easier to run and check (see tests/README.md) (by Michalis)
• @raises and @param is now supported at properties as well as methods. (by Michalis)
• Tipue (client-side search) improvements
• Parsing of $if and $elseif expressions, like {$if defined(MSWINDOWS) or defined(UNIX)...} (by Michalis)

The full release notes and all download links are on the GitHub release page.

Compared to FpDoc (because I suspect we have many FpDoc users here), PasDoc can read documentation from the comments in the Pascal sources, interpreting some special tags to designate formatting (although we can also read descriptions from external files). It is more similar to generators like JavaDoc and Doxygen in this regard. If you are interested in a comparison, we have a page that compares FpDoc and PasDoc in more detail.

[lucamar]

Well done. I can now delete a lot of lines in my "what I hate about PasDoc.txt" file and add a few more to the "why I love PasDoc.txt"

[PeterEvans]

When I click on the Download menu option, just under the work PasDoc, I get taken to SourceForge.

I am not sure if this was intended.

If I click on any of the 5 buttons I get a download from GitHub or go to GitHub. This seems correct.

[wp]

• Scan implementation section of a unit in addition to the interface section (by Fr0sT-Brutal)

Could it be that this feature is not yet available in the GUI version of pasdoc?

[michalis]

When I click on the Download menu option, just under the work PasDoc, I get taken to SourceForge.

I am not sure if this was intended.

If I click on any of the 5 buttons I get a download from GitHub or go to GitHub. This seems correct.

Fixed, thank you! All our download links should lead to GitHub now (For some reason, I missed notification about your forum post a ~month ago.)

• Scan implementation section of a unit in addition to the interface section (by Fr0sT-Brutal)

Could it be that this feature is not yet available in the GUI version of pasdoc?

Indeed, we missed adding this to the GUI version. You need to use command-line version now, https://pasdoc.github.io/ImplementationCommentsOption .

[wp]

Probably my stupidity, but I cannot get the commandline version to work as I intend to. Since there will probably a lot of parameters in the ende I thought I should collect all command line arguments in a parameter file which I pass to pasdoc via the @ symbol. I am using the following parameter file but I keep getting a "Fatal Error: EPasDoc: No Source Files have been specified.":

Code: [Select]

source=../../source/common/fpspreadsheet.pas
staronly
marker-optional
implementation-comments=join
The batch file in which I call pasdoc has this content:

Code: Bash  [Select][+][-]

1. set pasdoc_cmd=pasdoc.exe
2. set hhc_cmd="C:\Program Files (x86)\HTML Help Workshop\hhc.exe"
3.  
4. %pasdoc_cmd% --format htmlhelp --output output @fpspreadsheet.txt
5. %hhc_cmd% output/fpspreadsheet.hhc

Is there a way to use the pds file stored by the gui version as a parameter file for the @ command?

[wp]

Answering to myself: the "source" parameter does not refer to a pascal source file but to a file containing the names of the pascal sources.

[marcov]

Does anybody use pasdoc with chmcmd to compile the CHM projects?

[lucamar]

Does anybody use pasdoc with chmcmd to compile the CHM projects?

Now, that's a very good question. I've only ever used MS HTML Workshop but chmcmd should be usable also; AFAIR PasDoc doesn't generate (m)any of the more "advanced" features.

A good first test for this might be trying to generate the chm help files for Synapse.

[wp]

Today I changed the chm help generation of fpspreadsheet from Doc-O-matic to pasdoc. I can say: Excellent work in pasdoc!

Initially I created the chm file with the MS HMTL Help Workshop - which was quite easy because pasdoc creates the required hhp project file with everything required: simply load the hhp file into the workshop and click the compile button.

Then, motivated by this thread, I built myself a chmcmd binary from both FPC trunk and FPC 3.2. And - surprise -  each version can create the chm file correctly. There are a bunch of warnings and even error messages, maybe because I did not include all fpspreadsheet files in the help project, and thus there could be some links pointing into nowhere. But the chm file can be opened, and it seems to be working correctly.

I should mention, however, that chmcmd still has the old problem that it must be started from the folder with the hhp file.

[marcov]

I should mention, however, that chmcmd still has the old problem that it must be started from the folder with the hhp file.

I've looked up the report for this, and decided while serbod's solution wasn't ideal, it was better than nothing. Please test, then I might be able to pull this up to 3.2.2