|
22 | 22 |
|
23 | 23 | <meta name="viewport" content="width=device-width, initial-scale=1"> |
24 | 24 | <meta name="theme-color" content="#157878"> |
25 | | - <link rel="stylesheet" href="/assets/css/style.css?v=b56c76a091fccd5697365291748319e1f1540676"> |
| 25 | + <link rel="stylesheet" href="/assets/css/style.css?v=1287adce74463a8209e6e6fc4379e308c70fcba6"> |
26 | 26 | </head> |
27 | 27 | <body> |
28 | 28 | <div id="layout-container"> |
|
39 | 39 | <h1>--auto-abstract command-line option</h1> |
40 | 40 |
|
41 | 41 |
|
42 | | - <div class="sect1"> |
43 | | -<h2 id="_-overview"><a id="overview"></a> Overview</h2> |
44 | | -<div class="sectionbody"> |
45 | | -<div class="paragraph"> |
46 | | -<p>If you run pasdoc with --auto-abstract <a href="CommandLine">CommandLine</a> |
47 | | -option, pasdoc will automatically deduce the abstract description of |
48 | | -every item from the first sentence of it’s description. This means that |
49 | | -you can write</p> |
50 | | -</div> |
51 | | -<div class="listingblock"> |
52 | | -<div class="content"> |
53 | | -<pre class="pygments highlight" style="background: #f8f8f8;"><code data-lang="pascal"><span></span><span style="color: #008000; font-weight: bold">type</span> |
54 | | - <span style="color: #408080; font-style: italic">{ Short description of this class.</span> |
55 | | -<span style="color: #408080; font-style: italic"> More elaborate description of this class. }</span> |
56 | | - TMyClass <span style="color: #666666">=</span> <span style="color: #008000; font-weight: bold">class</span></code></pre> |
57 | | -</div> |
58 | | -</div> |
59 | | -<div class="paragraph"> |
60 | | -<p>and it’s equivalent to</p> |
61 | | -</div> |
62 | | -<div class="listingblock"> |
63 | | -<div class="content"> |
64 | | -<pre class="pygments highlight" style="background: #f8f8f8;"><code data-lang="pascal"><span></span><span style="color: #008000; font-weight: bold">type</span> |
65 | | - <span style="color: #408080; font-style: italic">{ @abstract(Short description of this class.)</span> |
66 | | -<span style="color: #408080; font-style: italic"> More elaborate description of this class. }</span> |
67 | | - TMyClass <span style="color: #666666">=</span> <span style="color: #008000; font-weight: bold">class</span></code></pre> |
68 | | -</div> |
69 | | -</div> |
70 | | -<div class="paragraph"> |
71 | | -<p>This means that you can avoid writing explicitly @abstract tags, which |
72 | | -means that your comments look less cluttered. Of course, this also means |
73 | | -that you have to carefully watch to make the first sentence of every |
74 | | -description to "stand on it’s own".</p> |
75 | | -</div> |
76 | | -<div class="paragraph"> |
77 | | -<p>This is a standard feature of javadoc, and it’s also available in |
78 | | -doxygen.</p> |
79 | | -</div> |
80 | | -<div class="paragraph"> |
81 | | -<p>The parsing logic is simple: the first sentence of the description ends |
82 | | -at the first period followed by any whitespace (including newline). Of |
83 | | -course this period must be in the "top-level" text, not inside parameter |
84 | | -of any @-tag. If there is no such period in the description, then the |
85 | | -<em>whole</em> description is treated as one sentence, and the <em>whole</em> |
86 | | -description is treated as an abstract description of the item.</p> |
87 | | -</div> |
88 | | -<div class="paragraph"> |
89 | | -<p>Of course if any description has an explicit @abstract section, then |
90 | | -this has priority over "the first sentence rule". Using explicit |
91 | | -@abstract tag may be useful if e.g. you need to make the abstract |
92 | | -description two-sentence long.</p> |
93 | | -</div> |
94 | | -</div> |
95 | | -</div> |
96 | | -<div class="sect1"> |
97 | | -<h2 id="_-small-difference-between-explicit-abstract"><a id="small-difference-between-explicit-abstract"></a> Small difference between explicit @abstract</h2> |
98 | | -<div class="sectionbody"> |
99 | | -<div class="paragraph"> |
100 | | -<p>Note that there is actually a small difference between two examples |
101 | | -given above. It occurs when pasdoc writes full description of a given |
102 | | -item (full = abstract one + the rest).</p> |
103 | | -</div> |
104 | | -<div class="paragraph"> |
105 | | -<p>If you used explicit @abstract tag, then pasdoc will always separate the |
106 | | -abstract description with some space (e.g. paragraph marker, <p>, in |
107 | | -HTML) from the rest of the description. But if your abstract description |
108 | | -was deduced automatically, then pasdoc will not automatically insert |
109 | | -such paragraph. This way full description of an item looks more like it |
110 | | -was specified in source code.</p> |
111 | | -</div> |
112 | | -<div class="paragraph"> |
113 | | -<p>So if I would really want to make two exactly equivalent examples, I |
114 | | -should show this as the first example (note that I explicitly inserted |
115 | | -empty line between abstract description and the rest here):</p> |
116 | | -</div> |
117 | | -<div class="listingblock"> |
118 | | -<div class="content"> |
119 | | -<pre class="pygments highlight" style="background: #f8f8f8;"><code data-lang="pascal"><span></span><span style="color: #008000; font-weight: bold">type</span> |
120 | | - <span style="color: #408080; font-style: italic">{ Short description of this class.</span> |
121 | | - |
122 | | -<span style="color: #408080; font-style: italic"> More elaborate description of this class. }</span> |
123 | | - TMyClass <span style="color: #666666">=</span> <span style="color: #008000; font-weight: bold">class</span> |
124 | | - <span style="color: #666666">...</span></code></pre> |
125 | | -</div> |
126 | | -</div> |
127 | | -</div> |
128 | | -</div> |
129 | | -<div class="sect1"> |
130 | | -<h2 id="_-example-unit"><a id="example-unit"></a> Example unit</h2> |
131 | | -<div class="sectionbody"> |
132 | | -<div class="paragraph"> |
133 | | -<p>See <a href="https://github.com/pasdoc/pasdoc/blob/master/tests/testcases/ok_auto_abstract.pas">test unit of this feature</a>.</p> |
134 | | -</div> |
135 | | -</div> |
| 42 | + <div class="paragraph"> |
| 43 | +<p>The <code>--auto-abstract</code> docs moved to the <a href="Abstract">Abstract Description</a> page of the documentation.</p> |
136 | 44 | </div> |
137 | 45 |
|
138 | 46 | <footer class="site-footer"> |
@@ -190,7 +98,7 @@ <h2 id="supported-tags"><a href="SupportedTags">Supported Tags</a>:</h2> |
190 | 98 |
|
191 | 99 | <ul> |
192 | 100 | <li> |
193 | | - <p><a href="AbstractTag">@abstract</a></p> |
| 101 | + <p><a href="Abstract">@abstract</a></p> |
194 | 102 | </li> |
195 | 103 | <li> |
196 | 104 | <p><a href="AuthorTag">@author</a></p> |
@@ -298,7 +206,7 @@ <h2 id="command-line"><a href="CommandLine">Command Line</a>:</h2> |
298 | 206 | </ul> |
299 | 207 | </li> |
300 | 208 | <li> |
301 | | - <p><a href="AutoAbstractOption">--auto-abstract</a></p> |
| 209 | + <p><a href="Abstract">--auto-abstract</a></p> |
302 | 210 | </li> |
303 | 211 | <li> |
304 | 212 | <p><a href="AutoBackComments">--auto-back-comments</a></p> |
@@ -372,6 +280,9 @@ <h2 id="command-line"><a href="CommandLine">Command Line</a>:</h2> |
372 | 280 | <li> |
373 | 281 | <p><a href="NameOption">--name</a></p> |
374 | 282 | </li> |
| 283 | + <li> |
| 284 | + <p><a href="Abstract">--no-auto-abstract</a></p> |
| 285 | + </li> |
375 | 286 | <li> |
376 | 287 | <p><a href="NoMacroOption">--no-macro</a></p> |
377 | 288 | </li> |
|
0 commit comments