• SortOption

By default, when pasdoc generates the documentation, it shows items in the same order as they were declared in your source files. That's because programmers usually write declarations of things in a sensible order, grouping similar things together and such, so preserving this order in the documentation makes sense.

However, if you want, pasdoc can sort items when generating documentation, i.e. always show them in alphabetical order. This is controlled by --sort CommandLine option. As an argument, this options takes the list of things that should be sorted in the final documentation (separated by commas):

• structures (this decides whether summary of classes / objects / records / interfaces is sorted on unit page)

• constants

• functions (this applies to global functions / procedures)

• types

• variables

• uses-clauses

• record-fields

• non-record-fields

• methods

• properties

Example: before 2005-05-25, it was hardcoded in pasdoc what things to sort (and what not). To get this behavior, run pasdoc like this:

pasdoc --sort=functions,record-fields,non-record-fields,methods,properties ...

Note that there is no way to control sorting of some index-like pages, like the listings of all units and all identifiers in HtmlOutput. Such listings are always presented in alphabetical order, because there is no "natural" order for these things.

Notes about some "unsafe" sortings (that you generally shouldn't use, because in some (rare) cases they can confuse human reading generated documentation):

• record-fields: people often use records to do some low-level memory tricks, and then order of fields of records matters. So you shouldn't sort them, unless you know that you want this.

  This is also the reason why sorting of records and non-records (classes / objects / interfaces) fields is controlled by separate values (record-fields and non-record-fields). As explained above, sorting of record fields may be "unsafe" (i.e. may produce inappropriate documentation). On the other hand, people don't do such low-level tricks with classes (even if such tricks are somewhat possible, they are always highly discouraged, since the memory layout of the class is the internal thing for the given compiler). So sorting of classes' fields is rather "safe".

• uses-clauses: it may be important in some cases to preserve order of units in your uses clause. When two units define the same identifier, the identifier from the last used unit "wins". So it's important to preserve this order in pasdoc-made documentation, otherwise reader of documentation could be uncertain about some issues. E.g. suppose you have a unit like

     1 unit Unit1, Unit2;
     2 interface
     3 type
     4   TMyNewType = TMyOldType;
     5 implementation
     6 end.
  

  and suppose that both Unit1 and Unit2 contain types named TMyOldType. So what actually is TMyNewType ? Answer is: TMyNewType is equal to Unit2.TMyOldType. That's because Unit2 is in the declararation clause after Unit1.

Sorting of other items is generally "safe" and is a matter of personal preference (and coding style), i.e. do you prefer identifiers to be presented always alphabetically or in the order they were declared.