PasDoc 1.0.0 release

michalis

Full Member
Posts: 146

We are proud to announce the release of PasDoc 1.0.0!

PasDoc is a documentation generator for Pascal source code. Documentation is generated from comments found in the source code (or in special description files). We support many output formats, like HTML, LaTeX (for PDF, PS), XML and PHP. We are free open-source software.

It's been 5 years since the previous release, and we have a lot of new features and fixes to share. We addressed some long-standing plans (like modernized HTML output look), we tested PasDoc understanding on some big codebases (like Delphi source code and FPC RTL). As such, we feel this release deserves a big grand 1.0.0 version number. Enjoy!

Download the latest release from our website where you will also find all the usage documentation.

If you have any feedback use our discussion forum and please report any bugs.

Most notable new features

Show source code position/link.
Modern look based on Bootstrap and more mobile-friendly.
Visibility of members can be toggled by a checkbox.
Show inherited members.
Automatic abstract is now default.
Show ancestor description for a method or class, when it misses its own description.
Ability to @link to specific overloaded routines, like @link(Foo(String,Integer)). See @link tag docs.
Much more complete expression evaluation for $if / $elseif. See details what is supported here.
Many parser extensions to be complete and handle really every Pascal source code in the wild. As an ultimate test before release, we tested parsing Delphi source code and parsing FPC RTL (and made numerous fixes to plug all the missing edge-cases). See also discussion thread.

All new features and bugfixes

Make automatic abstract (previously activated by --auto-abstract) enabled by default, and add --no-auto-abstract to disable it. See abstract description docs and discussion thread (Michalis)
Show inherited members of a class using --inherited-members, see also discussion thread (Michalis)
Support for linking to arbitrary qualified type identifiers, like TMyClass.TMyNestedClass.TAnotherNestedClass.TOriginalType and MyUnit.TMyClass.TMyNestedClass.TAnotherNestedClass.TOriginalType (Michalis)
If the type alias doesn't have a special description, we show the description from the type it aliases. Also parsing strong type aliases (with the type keyword) implemented. (Johann Elsass aka circular17, Michalis)
You can include some visibility members in a state "hidden by default" in the HTML output, and let user click on a checkbox (implemented using JS) to show them. Indicate the "included but hidden by default" visibility levels by ? suffix in --visible-members option, like --visible-members=public,protected?. See --visible-members docs and discussion thread (Michalis)
Accept identifiers with Unicode characters (not only ASCII letters) in them, both in UTF-8 and other (like Windows 1252) encodings, following Delphi. See also discussion thread (Michalis)
New PHP output, generates a map to find/enumerate Pascal identifiers present in HTML output (Michalis)
GraphViz classes graph shows implemented interfaces as dashed lines (Michalis)
Completely new default look: using the latest Bootstrap for modern base style, mobile-friendly, nicer visibility pills, new --css-based-on-bootstrap, show only available sections, backward compatible CSS preserved (Michalis)
New feature to show source code file/line + link in docs: --show-source-position, --source-url-pattern, --source-root, see also discussion thread (Michalis)
Added release (and CI build) on macOS/Aarch64 (Michalis)
Show ancestor description for a method or class, when it misses its own description. Scans ancestor class and interfaces and generates nice HTML output with ancestor descriptions. (Elliot Hillary)
Overloaded methods are now accounted for better (Elliot Hillary):

When using @link, you can link to a particular overload like @link(MyRoutine(Integer, String)) or @link(MyRoutine(Single)) instead of just @link(MyRoutine).
When generating HTML anchors, we add parameter types, so that each overloaded routine has a different anchor. This makes internal links (from @link, from internal tables) in the generated HTML output correct.
See @link tag docs for usage examples.

Much more complete expression evaluation for $if / $elseif (functions, subexpressions, negation, comparison, addition, multiplication). See conditional expressions docs (Johann Elsass aka circular17)
Ability to define macros on the command-line like -D FPC_FULLVERSION:=30202 that will be used for both regular Pascal code and in $if / $elseif evaluation. See conditional expressions docs (Johann Elsass aka circular17)
Proper "Constants" section in outputs for CIOs with nested constants (Michalis)
More complete "Hierarchy" at CIO pages by following also type aliases (Michalis)
Improved SimpleXML output (Michalis):
- Properly separate "name" from "declaration" for <variable>, <constant>, <type>
- Separate <label> inside <item> for definition lists
- <function> -> more general <routine>
- Nested structures (CIOs) and simple types inside other CIOs are now generated correctly
- Contains now deprecated / platform / etc. information, and proper unit name
- Add declaration=" to <property...>
- Remove visibility="..." from non-members (where the meaning is undefined)
- Added <aliased-name> to <type> for type aliases
PasDoc GUI exposes options to:
- Change output format to SimpleXML or PHP (in addition to existing ones, like HTML and LaTeX)
- Configure if CSS is based on Bootstrap or not
- Configure "Inherited members" (Michalis)
- Use Markdown and "automatic back comments" (Ayeseeem)
Manpages for pasdoc, pascal_pre_proc, file_to_pascal_data and file_to_pascal_string (Suve)
Parsing fixes:

Parsing and properly documenting type helpers (Johann Elsass aka circular17)
Parsing unit implementation with begin instead of initialization (Michalis)
Parsing unit implementation inline variable (Fr0sT-Brutal)
Fixed skipping UTF-8 BOM for various text files other than Pascal source (introduction, conclusion, CSS, HTML header/footer, include file) (Michalis)
Parsing objcclass and objcclass external (Michalis)
Parsing unimplemented directive (Michalis)
Parsing exports section (just skip it for now) (Michalis)
Parse noreturn (Michalis)
Allow on and out as regular names (e.g. for properties) (Michalis)
Parse align(N) directive at record end (Michalis)
Parse generics with multiple constraints separated by semicolons, like procedure Foo<A; B> (Michalis)
Parse anonymous record types (FField: record .. end) inside classes (Michalis)
Parse TSomething = type string; and record helper for string (Michalis)
Parse numbers in octal notation (Michalis)

Other fixes:

Fixed using introduction @shortTitle (Michalis)
Fixed resolving relative paths from introduction/conclusion (Michalis)
Fixes and improvements to Markdown support, and make Markdown [Descr](#Item) equivalent to @link (Fr0sT-Brutal)
Fixed spellchecking using Aspell, in previous version we didn't pass language arguments to aspell correctly
Fixed output when ancestor is not CIO (class, record or interface) for PasDoc (Michalis)
Fixed default visibility members (as documented, we hide private, strict private and implicit, and show the rest) (Michalis)
Fixed @exclude on nested types (Michalis)

Code cleanups, fixes to pass every auto-test with every compiler, CI improvements (Michalis)

Removed custom TStreamReader / TStreamWriter implementation, just rely on Delphi provided ones. This codepath is used only with STRING_UNICODE (only Delphi), so it's not a problem FPC 3.2.2 doesn't have TStreamReader (only later FPC has this).
Use generic containers from Generics.Collections, they rock with both FPC and Delphi, and make code both simpler (no need for some custom container code) and safer (no need to typecasts, types checked at compile-time). See discussion thread.
Fixed compilation and working with Delphi (Delphi 10 and up), using GitHub Actions, just like we do for Castle Game Engine.
Use standard TBufferedFileStream from both FPC and Delphi.
Removed a ton of unused old code from PasDoc_Utils, PasDoc_StreamUtils. We now rely on standard FPC and Delphi API for streams and Unicode handling.
Dropped compatibility with some ancient compiler versions. We require now compilers with Generics.Collections support, which means FPC >= 3.2.0 and Delphi >= 2009.
Nested classes parsing cleaned up (types nested in classes unified with global types, which solves a few accidental differences)
Dropped the undocumented and (as far as we know) unused possibility to modify the default set (instead of replacing it) of --visible-members and --sort. Previous PasDoc versions supported set elements with - and + suffixes, and if all items had such suffix, then we merely modified the default set. This was undocumented, also somewhat confusing to use (it only made sense if all elements had -/+ suffix, or none of them), and making code complicated.