Examples of command-line usage

These are CommandLine examples for PasDoc.

Simple examples

Create documentation using the default settings

pasdoc someunit.pas

  • someunit.pas will be searched in the current directory

  • verbosity is set to 2

  • no conditionals are defined

  • include files will be only found if located in the current directory

  • title will be empty

  • output format will be HTML

  • output path will be current directory

  • language will be English

  • any comment in the source will be used for the documentation

  • filenames will be generated using the form unit.type.html

  • member visibility will be set to protected,public,published,automated

Create documentation in German

pasdoc --language de someunit.pas

like above, but documentation will be in German. Of course this only applies to the parts of it generated by PasDoc, your comments will not be translated.

Create documentation in a subdirectory

pasdoc --output documentation someunit.pas

This will generate the html files in the subdirectory "documentation". The directory must already exist for this to work.

Use only ** style comments

pasdoc --staronly someunit.pas
pasdoc --marker=** someunit.pas

These two commands are equivalent. PasDoc will generate documentation only from the comments starting with {**, (*** and //**. Other comments are ignored.

Use a different comment marker

pasdoc --marker=: someunit.pas

This will generate documentation only from comments starting with //:, {: or (*: so any normal comments are ignored. This makes PasDoc compatible with some other similar tools like Time2Help.

Ignore a comment marker

pasdoc --marker=: --marker-optional someunit.pas

This will not require the marker : but rather use any comment and discard any leading :. Use this if you want to include any comments in the source code but without having an annoying : in front of each comment.

Search for include files in path

pasdoc --include ~/include someunit.pas pasdoc --include c:/include someunit.pas

The first example will search for include files in the subdirectory "include" of your home directory (under Linux of course).

The second example will search for include files in the directory "c:\include".

Multiple include directives

pasdoc --include /usr/local/include --include ~/include someunit.pas

PasDoc will in this case search for include files in all directories in the order they are specified.

Include debug code

pasdoc --define debug someunit.pas

Assuming you enclose your debug code with {$ifdef debug}…​{$endif} the example will include documentation on any debug code. Defines are not case sensitive.

Complex examples

Johannes example

Here is a script that I use for one project:

PasDoc \
 --output=doc/ \
 --write-uses-list \
 --visible-members=protected+ \
 `find source/ -iname '*.pas'` \
 --abbreviations=AUTHORS \
 '--marker=**' \
 --marker-optional \
 "--title=My Great Project" \
 $@

Lets go through this. First of all, you must know that this is a bash script, so the backslash at the end of the line just means to continue in the next line with parameters. The $@ means that parameters passed to this script are added at that point to the PasDoc parameters.

I want to use this for internal documentation, so I add protected members to the output using --visible-members=protected+. The find source/ -iname '*.pas' part is a Linux command to find all files named '*.pas'.

In my code, I use things like @author(johannes)` or @cvs($Author$) and therefore use an abbreviations file, it contains the following line:

johannes Johannes Berg <my@email.here>

I imported some code into this project that used '**' as a marker, I do not use any marker, so I just want to ignore the ** markers, and put it as a marker together with --marker-optional.

The title is in quotes completely because it contains spaces.

Fr0sT-Brutal example

Here is setup that I use for my project. It is tuned for the best possible natural look - minimum of special marks, usual // comments style, Markdown formatting.

pasdoc.opt file

name=SChannel helper
title=SChannel helper
format=html
auto-abstract
auto-link
auto-link-exclude=$CFG_PATH\autolink-excl
define=MSWINDOWS
markdown
ignore-marker= ~~
ignore-marker=TODO
auto-back-comments
visible-members=public,published,automated
implementation-comments=join
output=$CFG_PATH\docs

autolink-excl file

find
create
destroy
get
add
delete
count
clear
push
init
fin
stage
secure
shutdown

run.bat file

@ECHO OFF

SETLOCAL

SET CDir=%~dp0%
SET PasDoc=D:\Coding\PasDoc\pasdoc.exe

CALL "%PasDoc%" "@%CDir%\pasdoc.opt" "%CDir%\..\IcsSChannelSocket.pas" "%CDir%\..\SChannel.*.pas" || PAUSE

Here I use PasDoc’s ability to take options from file which is enabled by "@%optfilename%" argument.

Let’s examine non-trivial options inside:

  • auto-link - I want to auto generate cross-links for all identifiers…​

  • auto-link-exclude=$CFG_PATH\autolink-excl - …​but ignore some common words used for naming of some identifiers

  • define=MSWINDOWS - consider compiler define MSWINDOWS is set to include conditional regions

  • markdown - comments are formatted using Markdown

  • ignore-marker= ~~ - comments starting with space-and-double-tilda (// ~~) are skipped so I can use them for structuring:

// ~~ Init utils - usually not to be called by user ~~

// Mainly for internal use
procedure ...;

...

// ~~ Global init and fin ~~

// Load global stuff
procedure Init;

...

// ~~ Session init and fin ~~

// Init the session
procedure InitSession;
...

  • ignore-marker=TODO - comments that look like //TODO are ignored as well

  • auto-back-comments - one-line comments after an identifier are considered linked to that identifier without additional special char <

  • visible-members=public,published,automated - visibility of members for public docs

  • implementation-comments=join - join comments taken from interface and implementation sections of a unit allowing having both brief description at the beginning and full specification inside.

interface

// Function to prepare all necessary handshake data. No transport level actions.
// @raises ESSPIError on error
function DoClientHandshake(var SessionData: TSessionData; var HandShakeData: THandShakeData): SECURITY_STATUS;

implementation

{
 Function to prepare all necessary handshake data. No transport level actions.
   @param SessionData - [IN/OUT] record with session data
   @param HandShakeData - [IN/OUT] record with handshake data
   @raises ESSPIError on error

... very long description
}
function DoClientHandshake(var SessionData: TSessionData; var HandShakeData: THandShakeData): SECURITY_STATUS;

Check the generated docs here

PasDoc autodoc

PasDoc sources are parsed by PasDoc itself. Resulting documentation is available for viewing on PasDocAutoDoc page. You can see how this is done in PasDoc sources in source/autodoc/Makefile.