📄 comments.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head lang="en">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Language" content="en">
<meta name="author" content="Gerold Veith">
<meta name="description" content="How to write Comments for JADD - Just Another DelphiDoc, a program for automatic generation of documentation on Delphi source code.">
<meta name="keywords" content="Comments, Manual, Help, DelphiDoc, KylixDoc, JADD, Just Another DelphiDoc, Delphi, Kylix, Source Code">
<meta name="DC.Language" content="en">
<title>
How to write Comments for JADD - Just Another DelphiDoc
</title>
</head>
<body lang="en">
<p align=center>
<!-- local -->
<a href="http://sourceforge.net/"><img
src="sflogo.png"
width="210" height="62" border="0" alt="SourceForge.net Logo"
align="right"></a>
<!-- /local -->
<!-- public - -!
<a href="http://sourceforge.net/"><img
src="http://sourceforge.net/sflogo.php?group_id=113456&type=5"
width="210" height="62" border="0" alt="SourceForge.net Logo"
align="right"></a>
<!- - /public -->
Homepage: <a href="http://delphidoc.sourceforge.net/">http://delphidoc.sourceforge.net/</a><br>
Project-Page: <a href="http://sourceforge.net/projects/delphidoc/">http://sourceforge.net/projects/delphidoc/</a><br>
</p>
<br clear="all">
<h1>JADD - Just Another <em>DelphiDoc</em></h1>
Back to <a href="index.html">the main page</a> or
<a href="manual.html">the manual.</a>
<h1><a name="Comments">Comments</a></h1>
<p>This page describes the possibilities in the comments of the projects
you would like <em>DelphiDoc</em> to document. This means where the
comments are searched and what sections and commands are possible within
the comments to enrich the documentation.</p>
<p>The source code of <em>DelphiDoc</em> itself is fully commented
according to the possibilities outlined in here. If you need examples,
please take a look at it.</p>
<h2>Table of Contents</h2>
<ul>
<li><a href="#General">General</a></li>
<li><a href="#Sections">Sections</a></li>
<li><a href="#InlineCommands">Inline Commands</a></li>
<li><a href="#PredefinedTexts">Pre-defined Texts</a></li>
<li><a href="#VariableTexts">Variable Texts</a></li>
<li><a href="#TheEnd">The End</a></li>
</ul>
<h2><a name="General">General</a></h2>
<p>Comments are expected to be directly above the identifiers or on the
same line. This is the main requirement for comments. They don't have
to be tagged specially (f.i. by one or more stars "*") to be
considered by <em>DelphiDoc</em>. If for example a procedure is
commented several sections are expected, f.i. to describe the
parameters. If they are not found a warning will be logged but it will
nevertheless be documented. That is why even for not especially for
<em>DelphiDoc</em> commented projects documentation can be generated.
But the (correct) comments will only be used if they are at the above
mentioned position. But even without comments a useful documentation can
be created; through the generated linking an overview of the relations
of the identifiers can be generated.</p>
<p>There are several generators to generate completely different formats,
for this reason no native code of a format may be used, it would break
in other formats. There are several inline commands to format text and
add special things to the generated documentation that will work in
every format.<br>
As there are a few other tools out there which seem to only generate
documentation in HTML format and allow the use of those tags within the
comments, the generators of HTML also have
<a href="options.html#OptionTICBaseHTMLDoc">an option</a> to use these
tags without change.</p>
<h2><a name="Sections">Sections</a></h2>
<p>Comments are parsed, therefore they are split up in sections at first.
The character "~" (the tilde) is the special character, this
can be changed in <a href="options.html#OptionTSectionExtractor">the
options</a> of the extractor.<br>
Sections are initiated by <code>~sectionname</code>, you can also change
these names via the options of the extractor, as you can change the
special character "~".<p>
Syntax and Semantic of the Sections:
<dl>
<dt> Text</dt>
<dd>The default section contains the normal documentation. In some
cases the first sentence (at the moment only for functions in
the HTML-generator) will be used as an abstract.</dd>
<dt>~deprecated [Text]</dt>
<dd>Marks the identifier/the file as deprecated. This means it
shouldn't be used anymore and it will/would be deleted. The
possibly following text will be added to the documentation.</dd>
<dt>~todo Text</dt>
<dd>The text is added to the documentation and the identifier/file
is added to a list of things that still have to be done.</dd>
<dt>~feature Text</dt>
<dd>The text is added to the documentation and the identifier/file
is added to a list of features that can/should/could be
added.</dd>
<dt>~see Identifier[:Index] [Text]</dt>
<dd>A link on the given identifier is inserted in the documentation,
same syntax as with <a href="#icLink">~[link ]</a>.
A possibly following (short) text (f.e. a reason) is also
inserted. This section can be present several times.</dd>
<dt>~seeText Text</dt>
<dd>The text will also be inserted. Though it can be longer, it is
thought for short external links, f.i. to the help of Delphi.
This section can also be present several times.</dd>
<dt>~param ParamName[, ParamName]* Text</dt>
<dd>The text is used as documentation for the given parameter(s).
The text is evaluated for each parameter separately so that
f.i. a ~[inheritDoc] always evaluates to a different and correct
text. Usually there should be one section for each
parameter.</dd>
<dt>~result/return/returns Text</dt>
<dd>The documentation of the result of a function or function
type.</dd>
<dt>~exception/throws/raises ExceptionType Text</dt>
<dd>This section gives the type of an exception that could be thrown
by a function with an explanation when this could happen. It can
be present several times.</dd>
<dt>~example Text</dt>
<dd>An example to the identifier is given with this section. The
given text is inserted as an example in the documentation but
treated as normal text, that means code has to be formatted as
such (see below) if it is inside this section. This section can
be present several times.</dd>
<dt>~author</dt>
<dd>Creates an entry (or a list) with the following text.</dd>
<dt>~version</dt>
<dd>Creates an entry (or a list) with the following text.</dd>
<dt>~<i>???</i> (additional attributes)</dt>
<dd>Creates an entry (or a list) with the following text. The names
of the section have to be defined in the options of the
extractor named <code>SectionName_AdditionalAttribute1</code>.
There are three additional attributes defined so far. The
headers for the list can be defined by "localizing"
the texts <code>CommentAdditionalAttribute1</code> etc..</dd>
<dt>~page PageName (Title of Page) Text</dt>
<dd>This section is only valid in files read with
~[userDoc FilePath] to document the project not associated with
identifiers. To be exact the documentation ought to be in
sections of this kind. Each section represents a page of
documentation. The first argument is the name of the page, what
can be used to create links to it by ~[linkPage PageName].
The remnant of the line or, if it is empty the whole next
non-empty line, is used as the title of the page. The name
"Index" is reserved for the index of the
documentation. No inline commands may be used within the name or
the title.</dd>
<dt>~guiInclude NameOfFile</dt>
<dd>This section is only valid in text files with documentation as a
help on a GUI. Should in general be at the top of the file. The
denoted file is read as if it were part of the text file
itself.</dd>
<dt>~guiAlias Alias RealName</dt>
<dd>This section is only valid in text files with documentation as a
help on a GUI. Should in general be at the top of the file after
<code>~guiInclude</code>. It defines an alias for components,
i.e. instead of generating a link to the documentation of the
component <code>Alias</code> a link to the documentation of
<code>RealName</code> is generated. As the help context of the
components using a documentation topic is used for it, all
components using a topic must have the same help context, i.e.
both components <code>Alias</code> and <code>RealName</code> in
this example. The <code>RealName</code> may also be a defined
alias, but there shouldn't be any circular aliases.</dd>
<dt>~guiManual Left,Top,Right,Bottom Link</dt>
<dd>This section is only valid in text files with documentation as a
help on a GUI. Should in general be before any
<code>~gui</code> sections. It defines an additional link region
in the screen shot, with that it has some similarities with the
inline command <a href="#icimageLink">~[imageLink ]</a>. The
coordinates are integer values in pixels inside the screen shot.
The link should be the name of a documentation topic as defined
by a <code>~gui</code> section. If it is not a known
documentation topic it will be treated as an URI in the WWW and
a warning message will be logged.</dd>
<dt>~gui TopicName (Title of Topic) Text</dt>
<dd>This section is only valid in text files with documentation as a
help on a GUI. Should in general be after any other sections in
the file. The name is the name of the component to be documented
and is used in any link in the screen shot (from the log file
and any manual link with <code>~guiManual</code>) and in the
inline command <code>~[linkGUI ]</code>. The remnant of the line
or, if it is empty the whole next non-empty line, is used as the
title for the topic of documentation. No inline commands may be
used within the name or the title. There should be a topic for
each component that is not aliased to another one.<br>
There are three special topic names: <code>.preface</code>,
<code>.epilogue</code> and <code>.default</code>. The preface
will be inserted above the screen shot and sometimes above all
topics (depending on the generator), the epilogue accordingly
after the screen shot and maybe after each topic. Default
describes the default comment for any component that is not
documented.</dd>
</dl>
<h2><a name="InlineCommands">Inline Commands</a></h2>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -