CommandlineExamples

Michalis Kamburelis edited this page Jan 8, 2017 · 16 revisions
Clone this wiki locally

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.

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.