Time2HELP's Documentation Model

DocComments v.s. External Documentation
Time2HELP can be seen as a repository/database containing information about your source code. You provide Time2HELP with it's information by telling it which source code files (units) to parse, as well as optional files containing "external" information/documentation about your code. Time2HELP can extract your documentation both from specially formatted comments within your source code ( "DocComments") and from documentation stored in separate files called UnitDoc files (Documentation about a Unit).

You can use both styles of documentation, even for the same unit, as the information from both will be "merged" within Time2HELP's internal database. But note that the External Documentation (UnitDoc) takes preference ("overrides") the DocComment if the same item (e.g. a method) is documented in both in a DocComment and in a UnitDoc file.

Whether you should use DocComments or UnitDocs (keeping the Doc in external files) depends upon your situation and personal preference.

Reasons to use external documentation

• You may not be responsible for updates to the code you want to document, the code may be updated by a third party. This makes it unacceptable to use "in-source" documentation.
• If you want to make documentation in multiple langauges, you may use DocComments for your favourite language, and document it using separate UnitDocs (one for each language for each unit) for the other languages. (You aren't forced to use DocComment for your favourite language, you may perfectly well document using UnitDocs only.)
• You may not like to clutter you code with lots of "non-code" text, examples etc.
• You have to recompile more of your code when doing incremental compiles within Delphi if you use DocComments, as Delphi doesn't know whether you modify a DocComment or a "real" part of the code..
• If the programmer and the documentation writer are separate persons, using UnitDocs is natural, as then the documentation writer cannot by accident modify the source code (proper), and the programmer may work on the unit (more or less) independently of the documentation writer.

Reasons to use in-source (DocComments) documentation

• You are less "vulnerable" to name changes (method names, class names etc), which you may often do before the code "stabilizes", and it's easier to move code around to other units. An option which may suit you is to use DocComments exclusively, or until the code has "stabilized", and then switch to UnitDocs.
• Less danger of documentation getting out of sync with code, as documentation and code are located in the same file, and very "near" to each other.
• When writing code, having to change context to write the documentation may abrupt the mental flow, and it may be very important to write the documentation when you have it fresh in mind.