I'm one of pasdoc's developers. I use pasdoc to document my open sourced ObjectPascal code (VRML + OpenGL + OpenAL = 3d game engine). My webpage is http://michalis.ii.uni.wroc.pl/~michalis/

Contents

  1. Adding new feature to pasdoc
  2. Should documentation be placed inside units interface, or in separate files ?
  3. Some TODO things
    1. New output formats
      1. Plain text output
      2. Fpdoc output
      3. Texinfo output
    2. Support for groups of items
    3. Sections
    4. More wiki-like syntax for pasdoc descriptions
  4. How did I convert pages from old pasdoc wiki (using phpwiki) to this wiki (using moinmoin) ?

Adding new feature to pasdoc

When adding new end-user visible feature, remember to always

Should documentation be placed inside units interface, or in separate files ?

Stating it differently, which way is better:

  1. Mix the comments with the sources, like javadoc, ocamldoc, pasdoc and many others do. You put comments inside source files, before each declared item, and then documentation generator parses source files and extracts those comments into documentation.

  2. Separate the comments from the sources, like fpdoc does. You put comments inside a separate XML file.

Below are some of my thoughs about this. If you don't have time to read this, here's my conclusion: I really don't think that one way or the other is ultimately better. I prefer the "mix the comments with the sources" way, but I would be absolutely happy also using a documentation generator with an approach "separate the comments from the sources". Well, actually I did, I used and tested fpdoc a little, and I like it very much. No doubt, pasdoc can learn a few things from fpdoc (actually, some of the features I done in pasdoc were inspired by fpdoc behavior).

A common argument against "mix with sources" approach is that when the documentation gets larger, it tends to clutter unit's interface. I don't think that this is a real problem because:

  1. First of all, I don't think about that as a clutter. Units interface specification without any documentation is good for compilers, not for humans. It's especially important for new people, that read your source code for the 1st time. Documentation makes unit's source larger, but it's just an essential part of a unit.

  2. That said, it's sometimes useful for someone to get a "higher-level" view of the way unit's interface is written. The solution is: look at documentation generated by pasdoc. pasdoc HtmlOutput presents a nice summary view of each unit and of each class. This summary is clear, compact and uncluttered. Moreover, output of pasdoc presents some other summary views, that are not available when looking at the unit's source: "all-items" pages (e.g. "all identifiers" page, "all classes", etc.), class hierarchy diagram and even some graphviz graphs with class hierarchy and unit dependency. So if you really prefer to just forget about all this documentation strings for now and just see the list of declared identifiers, then look at documentation generated by pasdoc. BTW, The same is true for fpdoc. Both pasdoc and fpdoc (and any other doc generator for other language) present in final documentation both a nice summary and a nice detailed descriptions for documented units. The difference between fpdoc and pasdoc comes when you look at units source code: if pasdoc was used, the unit's source code is cluttered with comments. If fpdoc was used, the unit's source is compact and not cluttered, but you don't immediately see documentation.

Conclusion: for programmers already familiar with the unit source, it doesn't matter. They are familiar with unit source, and even an interface largely mixed with a large comments looks "clear and compact" for them. I know that this is the case for me and many of my units. For programmers new to the unit source: "separate from sources" approach looks better, more compact, but is without documentation. So is it really useful ? Ultimately, the answer remains "both approaches, mix with sources and separate from sources, are equally good". In each approach, the generated output provides all the advantages: you can see both a compact summary and a large detailed descriptions there.

Some additional arguments:

Some TODO things

Some larger things that I want to implement in pasdoc. No, I'm not currently working at them, I have many smaller to-dos now. Features below are on my long-term plan.

New output formats

Plain text output

This has two purposes:

  1. To be a demo of a simple output generator, potentially useful to anyone else who would like to write new output generator and would like to see how it can be done (existing html and latex generators are not good examples of "simple generators").
  2. And as a side-effect, we will use it to generate plain-text data that is easier to search by tipue.

    For now you can't search using tipue for special characters that are escaped in html using &-references. Search engine will just not see these characters correctly. Also, when you search for a word like class search engine incorrectly finds items with code like <tag class="...">, i.e. it finds word class inside html tag. This will be fixed by converting RawDescription to plain text. Short description placed in index entry will be as AbstractDescription in plain text, long description will be DetailedDescription + Params + etc. also in plain text.

Fpdoc output

Output to fpdoc input format. Text below will be moved to FpdocOutput page when this will be implemented.

Free Pascal code documenter, fpdoc, is a program distributed and developed as part of FreePascal. It's goal is similar to pasdoc: parse Pascal units and generate documentation for them. But, unlike pasdoc, fpdoc does not read descriptions of items from the comments placed in unit's source file. Instead you put your descriptions in a separate XML file. fpdoc reads both the unit's source file and the XML file with descriptions and generates documentation from them. See fpdoc reference manual online for more information.

When you tell pasdoc to use fpdoc output then pasdoc will write documentation in fpdoc's XML format. This means that after running pasdoc, you get a file docs.xml (unless you changed "docs" to something else using --name option). Then you can run fpdoc, telling fpdoc to again parse the same unit source files and additionally to take generated docs.xml file. And then you get documentation generated by fpdoc.

Why this is useful ?

Texinfo output

Just because I like it :)

Support for groups of items

Group of items are items that share a common documentation string.

The idea is that you write one documentation string for a group of items. In generated documentation, this group of items is documented as one item, e.g. 

=== procedure BlahBlah1; ===

Normal doc string for procedure BlahBlah1.

=== procedure Foo and
    procedure Bar and
    procedure Xyz      ===

One doc string that describes at once three procedures
Foo, Bar and Xyz.

=== procedure BlahBlah2 ===

Normal doc string for procedure BlahBlah2.

So the idea is that the items in one group not only share the same documentation string, but also that user reading this documentation clearly sees that these three items are documented in one place by one doc string. In other words: no, this can't be implemented by simply copying the same doc string to a couple of items. This must be clear and readable, so that user reading documentation can immediately see that some items are grouped. So this will require special support in each doc final format.

Syntax 1: 

   1 { One comment that describes at once three procedures
   2   Foo, Bar and Xyz.
   3 
   4   @groupbegin }
   5 procedure Foo;
   6 procedure Bar;
   7 procedure Xyz;
   8 { @groupend }

Some rules :

Syntax 2: Alternative syntax that produces exactly the same results, is more troublesome to write but also gives more possibilities for human writing docs : 

   1 { One comment that describes at once three procedures
   2   Foo, Bar and Xyz. }
   3 procedure Foo;
   4 
   5 { @groupwith(Foo) }
   6 procedure Bar;
   7 
   8 { @groupwith(Foo) }
   9 procedure Xyz;

Rule:

Two syntaxes can be mixed, e.g. 3rd equivalent version of the same example is 

   1 { One comment that describes at once three procedures
   2   Foo, Bar and Xyz.
   3 
   4   @groupbegin }
   5 procedure Foo;
   6 procedure Bar;
   7 { @groupend }
   8 
   9 { @groupwith(Foo) }
  10 procedure Xyz;

Rules not dependent on any syntax:

Note that multiple variables defined at once, like this: 

   1 { Some docs for A, B, C }
   2 A, B, C: Integer;

would be automatically grouped together. Currently this is equivalent to 

   1 { Some docs for A, B, C }
   2 A: Integer;
   3 { Some docs for A, B, C }
   4 B: Integer;
   5 { Some docs for A, B, C }
   6 C: Integer;

which means that description "Some docs for A, B, C" is copied three times in the documentation. This is bad, because the information that items A, B and C are documented togther, at once, is lost (i.e. user reading the docs does may not immediately see this).

Another advantage of this would be when we generate "All Functions and Procedures", "All Identifiers" etc. listings. If two (or more) items that are in the same group will be shown in successive rows of these listings (e.g. when items are overloaded versions of the same proc, and they are wrapped in one group) then we can squish them and present them as one table row (because all these items have the same description).

Sections

Support for sections, that divide unit into a couple of separate blocks but are not tied to any particular item (something in the spirit of ocamldoc's "{1 Section title}"). Format is 

{ @section(Section title)
  Additional comments about section. }

E.g. 

{ @section(Utilities that deal with strings)

  Every string routine in this section is able to handle MBCS strings.
  Unless otherwise noted, all string comparisons are case-sensitive.
}

Page of each unit should present hyperlinked table of contents of sections within this unit. Sections are only presented when looking at unit's page.

Also LaTeX-like @subsection and @subsubsection could be nice ? Or (copying ocamldoc's idea) just add a number to each section, i.e. 

  @section(1 Main section title)
  @section(2 Sub section title)

is used instead of 

  @section(Main section title)
  @subsection(Sub section title)

? I think that I prefer using "sub" prefixes, but this is negotiable.

Of course, it is not mandatory, not even desirable, to divide every unit you document into sections. This feature has it's best use when you have a large unit with many global procedures/functions – then by using sections you can nicely indicate to reader that routines in this unit can be logically divided into separate sections, like

Note that sections and groups (proposed in the previous point) somewhat complement each other.

In summary, this feature is like splitting a large unit to many "sub-units" in documentation.

More wiki-like syntax for pasdoc descriptions

Wiki-like syntax means that you can achieve some (formatting) effect without using any @-tag. Some existing features of pasdoc descriptions are already wiki-like syntax (see WritingDocumentation):

More wiki-like features are planned. The following things should be achievable with wiki-like syntax:

Notes:

How did I convert pages from old pasdoc wiki (using phpwiki) to this wiki (using moinmoin) ?

I use my EmacsLisp functions to automatically convert with regexps as much as I can. These functions are far from perfect, but usually they produce ready or almost ready moinmoin page. Here are these functions (note that kam- is my personal prefix): 

(defun kam-beg-of-buf ()
  "Like `beginning-of-buffer' but don't set mark."
  (interactive)
  (goto-char (point-min))
)

(defun kam-simple-re-replace (from-string to-string from-pos
  &optional end-pos fixedcase)
  "Replace text in current buffer from FROM-STRING to TO-STRING,
starting from position FROM-POS to END-POS (END-POS = nil means
to the end of buffer).

Current position of cursor is not changed by this function.
Uses regexps. FIXEDCASE has the same meaning as in `replace-match'."
  (save-excursion
    (goto-char from-pos)
    (while (re-search-forward from-string end-pos t)
      (replace-match to-string fixedcase nil)))
)

(defun kam-simple-re-replace-buffer (from-string to-string)
  "Simple regexp replace in whole buffer. Without asking user."
  (interactive)
  (kam-simple-re-replace from-string to-string (point-min))
)

(defun kam-phpwiki-to-moinmoin ()
  (interactive)

  ;; list (must start with spaces + *)
  (kam-simple-re-replace-buffer "^-\\([^-]\\)" "  *\\1")
  (kam-simple-re-replace-buffer "^*" "  *")
  (kam-simple-re-replace-buffer "^;" "  *")

  ;; quote by `` inside
  (kam-simple-re-replace-buffer "~PasDoc" "Pas``Doc")

  ;; tt font (must be before headings)
  (kam-simple-re-replace-buffer "=\\([^=]*\\)=" "{ { {\\1} } }")
  (kam-simple-re-replace-buffer "<pre>" "{ { {")
  (kam-simple-re-replace-buffer "</pre>" "} } }")

  ;; headings (note that meaning is reversed,
  (kam-simple-re-replace-buffer "^!!\\([^!].*\\)$" "= \\1 =")
  (kam-simple-re-replace-buffer "^!\\([^!].*\\)$" "== \\1 ==")

  ;; links [] with custom label
  (kam-simple-re-replace-buffer "\\[\\(.*?\\)|\\(http.*?\\)\\]" "[\\2 \\1]")
  (kam-simple-re-replace-buffer "\\[\\(.*?\\)|\\(.*?\\)\\]" "[:\\2:\\1]")

  ;; using [a-zA-Z] to force page name
  (kam-simple-re-replace-buffer "\\[\\([a-zA-Z0-9]*\\)\\]" "[\"\\1\"]")

  ;; rules (while 4 - is accepted by moinmoin, it makes too thin rule)
  (kam-simple-re-replace-buffer "----" "-----")

  (kam-simple-re-replace-buffer "HomePage" "FrontPage")
)

(defun kam-phpwiki-changes-log-to-moinmoin ()
  (interactive)
  (kam-beg-of-buf)
  (insert "This page was converted from old pasdoc wiki that used phpwiki engine.
Below you can see page history from phpwiki.

")
  (kam-simple-re-replace-buffer "^" "## ")
)

(Note that I had to "escape" three consecutive { and } characters in code above (around replacing </pre>))

Conversion of every page goes like:

MichalisKamburelis (last edited 2008-08-03 06:18:32 by Hans-Peter Diettrich)