PasDoc 1.0.0 release with with many features and fixes: modern HTML look, show source position, visibility of membes toggleable, show inherited members

News
1
Castle Game Engine API generated by PasDoc

This a bit non-standard news post: I wanted to announce a new release of PasDoc, documentation generator we use to create Castle Game Engine API docs.

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

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.