|
In this page, I will explain how to write JavaDoc comments
for DelphiCodeToDoc in the Delphi environment. You can read this
interresting article from Sun : How
to Write Doc Comments for the Javadoc Tool.
The text below is only a summary of this document. See full list
of TAGs at the end of this document.
Format of a Doc Comment
A doc comment is written in HTML and must precede a class, field,
constructor or method declaration. It is made up of two parts
-- a description followed by block tags. In this example, there
is one block tags are @param, and @see.
Example
| |
{*------------------------------------------------------------------------------
Configure the User output and Debug output to
inform about the status
The TDOCProject class is very separated from
the external user interface.
But in order to inform about the state of the
project, it needs to know where
to display informations. This could be a visual
control, or a file or whatever
containing a TStrings reference to work.
@param dmUser
Where User messages will be written
@param dmDebug
Where Debug messages will be written
@see WriteMessage
-------------------------------------------------------------------------------}
procedure TDOCProject.SetDestinationMessages(const
dmUser, dmDebug: TStrings);
begin
FdmUserMessages := dmUser;
FdmDebugMessages := dmDebug;
end;
|
| |
|
Note
*The resulting HTML from running DelphiCodeToDoc
is shown below.
*Each line above is indented to align with the code below the
comment (the begin/end block).
*The first line contains the begin-comment delimiter "{"
followed by the JavaDoc Prefix '*' and the embellishment, which
is optionnal.
*Write the first sentence as a short summary of the method, as
DelphiCodeToDoc automatically places it in the method summary
table (and index).
*Insert a blank comment line between the description and the list
of tags, as shown.
*The first line that begins with an "@" character ends
the description. There is only one description block per doc comment;
you cannot continue the description following block tags.
*The last line contains the end-comment delimiter "}",
forgoing with an embellishment.
*Lines won't wrap, limit any doc-comment lines to 80 characters.
Here is what the previous example
would look like after running the Javadoc tool:
| |
Member
Visibility
Related Class
Description
| |
Configure the User output and Debug output to inform
about the status
|
| |
The TDOCProject class is very separated from the
external user interface.
|
| |
But in order to inform about the state of the project,
it needs to know where
|
| |
to display informations. This could be a visual control,
or a file or whatever
|
| |
containing a TStrings reference to work.
|
| |
|
Source code
| |
procedure SetDestinationMessages
( const dmUser , dmDebug : TStrings ) |
Parameters
| |
| Parameter |
Description |
| dmUser : TStrings |
Where User messages will
be written |
| dmDebug : TStrings |
Where Debug messages will
be written |
|
Links
|
List of supported
TAGs, explaination and example:
*Description (no '@'
TAG!)
*@author
*@version
*@param
*@return
*@throws
*@todo
*@Comment (and special
inline extended comment)
*@see (Not functionnal for the moment
in DelphiCodeToDoc)
|
