Documentation written in the source code itself must be inside comments, and in order for Time2HELP not to confuse what comments is meant for it, and what is only meant for other programmers to read (and formatting comments etc.), Time2HELP looks for comments starting with a "magic" symbol. We allow ":" and "**" as "magic symbols" (the latter is taken from JavaDoc).
The DocComment must be located before the item in question.
Source Code Example
//:Contains a wrapper for the TDLDebugWindow OLE-Automation Object
unit L1DebugWindow;
interface
uses DLDebugWindow_TLB;
Type
{:Simple "Visual Basic like" Debug object.}
// -----------------------------------------------------------------------
TL1DebugWindow=class(TObject)
// -----------------------------------------------------------------------
public
{:Prints a message to the debug window.
@param i_str The string to output to the debug server.
@example Use code similar to the below to send messages to the debug server:<Br/>
<Code>
Debug.Print('Oh no! This should never happen!');
</Code>}
Procedure Print(const i_str: String);
End; |
Note the use of @param and @example, these are called "Alpha-tags" (or @-tags). These are as in the JavaDoc system. Properties, methods and events may have DocComments in both the interface and the implementation section. If a method have both an interface DocComment and an implementation DocComment, these are concatenated (and a "." may be inserted at the end of the interface DocComment).
Documentation Conflicts
Instead of keeping your documentation in the source code, you can keep it in external files ("UnitDocs"). If you document one function (A) in a unit in a UnitDoc (external) file, and document another function (B) in the same unit using DocComments, Time2HELP will include both function's documentation in the resulting help file. If you document both functions using DocComments, but also function A externally, Time2HELP will in the resulting help file use the internal documentation for B, but the external documentation for A. (i.e. it gives preference to external/UnitDoc documentation).
Unit Documentation
When T2H sees the 'Unit' keyword, it assumes that any current DocComment belongs to the documentation of the unit itself.
|
|