source: trunk/SRC/Documentation/idldoc/templates/dev-help.tt @ 191

Last change on this file since 191 was 69, checked in by smasson, 18 years ago

debug + new xxx
File size: 15.8 KB
Line 
1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<!-- Template needs structure with the following fields:
6       version : IDLdoc version
7       date : string containing date of file creation
8       embed : 0 for link to CSS, 1 for embed CSS
9       css_location : if embed then string filename of CSS file location, o/w href to CSS file
10       idldoc_syntax_filename : file containing IDLdoc output for the idldoc routine
11       navbar_filename : filename of navbar template
12       footer : filename of footer file to include
13       tagline_filename : filename of tagline template
14     Plus stuff needed by the templates: navbar, tagline
15-->
16
17<!-- Generated by IDLdoc [% version %] on [% date %] -->
18
19<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
20  <head>
21    <title>IDLdoc Developer's Help ([% title %])</title>
22
23    [% IF embed %]
24    <style type="text/css" media="all">
25         [% INCLUDE css_location %]
26    </style>   
27    <style type="text/css" media="print">
28         [% INCLUDE print_css_location %]
29    </style>
30    [% ELSE %]
31    <link rel="stylesheet" type="text/css" href="[% root %]/main_files.css" media="all"/>
32    <link rel="stylesheet" type="text/css" href="[% root %]/main_files_print.css" media="print"/>
33    [% END %]
34
35    <script type="text/javascript">
36      function setTitle() {
37        parent.document.title="IDLdoc Developer's Help ([% title %])";
38      }
39    </script>
40  </head>
41
42
43  <body onload="setTitle();">
44   
45    [% INCLUDE_TEMPLATE navbar_filename %]
46   
47    <div id="container">
48
49      <h1>IDLdoc developer's guide</h1>
50
51      <p>This guide discusses how to mark up IDL pro code in order to
52      insert more information into IDLdoc's output.</p>
53
54      <p>Comments on the routine and file level are placed between
55      ";+" and ";-" lines before a routine in IDL source code. Content
56      between these lines is copied verbatim into the IDLdoc output
57      for the routine it appears before with the exception of the
58      @-preceded "tags" listed in tables below. Once an @ appears in
59      the comments, IDLdoc processes all remaining lines of the
60      comments as tags. To place a non-tag defining "@" in your
61      comments, escape it with a "\", as in
62      "email_address\@rsinc.com".</p>
63
64      <p>In the following example, the @author tag is used to indicate
65      an author of the code. The second "@" is escaped to allow its
66      literal use in the email address:</p>
67
68        <pre class="snippet">; @author Michael Galloy, mgalloy\@rsinc.com</pre>
69
70      <h2>Routine level comments</h2>
71
72      <p>There are many tags which describe an individual
73      routine. Each tag name appears after an "@" sign as the first
74      non-whitespace character after the ;. The tags are described
75      below.</p>
76
77      <table class="basic" cellspacing="0">
78        <tr>
79          <th>Tag</th>
80          <th>Description</th>
81        </tr>
82        <tr>
83          <td>abstract</td>
84          <td>
85            Presence of the this tag indicates this method is
86            abstract. This is intended for use with methods of a class
87            which are not intended to be called, but are only provided
88            as documenting an interface that a subclass will override.
89          </td>
90        </tr>
91        <tr>
92          <td>author</td>
93          <td>
94            Text following this tag appears in a list of attributes
95            of the routine marked as "Author."
96          </td>
97        </tr>
98        <tr>
99          <td>bugs</td>
100          <td>
101            Text that follows this tag is copied into a bug
102            attribute of the routine and placed in a library wide
103            listing which documents known failings of routines.
104          </td>
105        </tr>
106        <tr>
107          <td>categories</td>
108          <td>
109            Text following this tag is used as a comma separated list
110            of categories of the routine. The syntax is:
111
112            <pre class="snippet">; @categories math, input/output</pre>
113
114            Category names are case-sensitive and may contain any
115            characters except commas (though whitespace at the
116            beginning and end will be removed).
117          </td>
118        </tr>
119        <tr>
120          <td>copyright</td>
121          <td>
122            Text following this tag appears in a list of attributes
123            of the routine marked as "Copyright."
124          </td>
125        </tr>
126        <tr>
127          <td>customer_id</td>
128          <td>
129            Text following this tag appears in a list of attributes
130            of the routine marked as "Customer ID."
131          </td>
132        </tr>
133        <tr>
134          <td>examples</td>
135          <td>
136            Text following this tag is copied into an examples
137            attribute of the routine; it is intended to have
138            example code of using the routine.
139          </td>
140        </tr>
141        <tr>
142          <td>field</td>
143          <td>
144            For routines in files that end in "__define", this
145            provides documentation of a member variable of a
146            class/structure. The syntax is
147           
148            <pre class="snippet">; @field field_name comment</pre>
149           
150            where "field" matches one of the structure field names
151            of the structure type/class being defined.
152          </td>
153        </tr>
154        <tr>
155          <td>hidden</td>
156          <td>
157            Presence of this tag hides this routine in IDLdoc
158            output.
159          </td>
160        </tr>
161        <tr>
162          <td>history</td>
163          <td>
164            Text following this tag is copied into a history
165            attribute of the routine; it is intended to have a
166            history of the creators and modifiers of the source
167            code of the routine.
168          </td>
169        </tr>
170        <tr>
171          <td>inherits</td>
172          <td>
173            Obsolete. Intended to provide the parent class of the
174            documented class, but this is automatically handled by
175            IDLdoc now (as long as class definitions are in files
176            that end "__define").
177          </td>
178        </tr>
179        <tr>
180          <td>keyword</td>
181          <td>
182            This tag documents a single keyword parameter to the
183            routine. This syntax is
184           
185            <pre class="snippet">; @keyword keyword_name attributes comment</pre>
186           
187            Attributes further describe keyword and detailed in
188            the section below. The comment may be an text and is
189            copied into the IDLdoc output.
190          </td>
191        </tr>
192        <tr>
193          <td>obsolete</td>
194          <td>
195            Presence of this tag marks the routine as obsolete.
196          </td>
197        </tr>
198        <tr>
199          <td>param</td>
200          <td>
201            This tag documents a single keyword parameter to the
202            routine. This syntax is
203           
204            <pre class="snippet">; @param keyword_name attributes comment</pre>
205           
206            Attributes further describe keyword and detailed in
207            the section below. The comment may be an text and is
208            copied into the IDLdoc output.
209          </td>
210        </tr>
211        <tr>
212          <td>pre</td>
213          <td>
214            Text following this tag will be copied to a pre
215            attribute of the routine; it is intended to give
216            conditions the routine assumes to be true before it
217            runs.
218          </td>
219        </tr>
220        <tr>
221          <td>post</td>
222          <td>
223            Text following this tag will be copied to a post
224            attribute of the routine; it is intended to give
225            conditions the routine assumes to be true after it
226            runs.
227          </td>
228        </tr>
229        <tr>
230          <td>private</td>
231          <td>
232            Presence of this tag will hide this routine in IDLdoc
233            output if IDLdoc is run in "user" mode.
234          </td>
235        </tr>
236        <tr>
237          <td>requires</td>
238          <td>
239            Text following this tag is copied into the "Requires"
240            attribute of the routine; it is intended to provide
241            the version of IDL required to run the routine. For
242            example,
243           
244            <pre class="snippet">; @requires IDL 6.2</pre>
245           
246            will simply cause "IDL 6.2" to appear in the
247            "Requires" attribute.
248          </td>
249        </tr>
250        <tr>
251          <td>restrictions</td>
252          <td>
253            Text following this tag is copied into the
254            "Restrictions" attribute of the routine; it is
255            intended to provide any restrictions on the use of the
256            routine.
257          </td>
258        </tr>
259        <tr>
260          <td>returns</td>
261          <td>
262            Text following this tag is copied into the "Returns"
263            attribute of the routine; it is intended to provide
264            information about return value of a function.
265          </td>
266        </tr>
267        <tr>
268          <td>todo</td>
269          <td>
270            This tag places an item in a library-wide list of todo
271            items. The text following the tag is copied into this list
272            along with the routine it appears in it.
273          </td>
274        </tr>
275        <tr>
276          <td>uses</td>
277          <td>
278            Text following this tag is placed in a uses attribute of
279            the routine; it is intended to list routines that this
280            routine calls.
281          </td>
282        </tr>
283        <tr>
284          <td>version</td>
285          <td>
286            Text following this tag is placed in a version attribute
287            of the routine; it is intended to give a version
288            name/number of the routine.
289          </td>
290        </tr>
291      </table>
292     
293      <p>For each positional parameters or keyword tag additional
294      attributes may be added in curly braces. For example,</p>
295       
296      <pre class="snippet">; @param x {in}{required}{type=lonarr} x-axis data</pre>
297       
298      <p>The attributes are described below.</p>
299     
300      <table class="basic" cellspacing="0">
301        <tr>
302          <th>Attribute</th>
303          <th>Description</th>
304        </tr>
305        <tr>
306          <td>default</td>
307          <td>
308            This atrribute defines the default value of the
309            parameter. Any string may be entered and is echoed in the
310            IDLdoc output.
311          </td>
312        </tr>
313        <tr>
314          <td>hidden</td>
315          <td>
316            This attribute hides this parameter in IDLdoc output.
317          </td>
318        </tr>
319        <tr>
320          <td>in</td>
321          <td>
322            This attribute marks the parameter as an input to the
323            routine.
324          </td>
325        </tr>
326        <tr>
327          <td>optional</td>
328          <td>
329            This attribute marks the parameter as optional; the
330            routine does not always need this parameter, although
331            there might be cases where the parameter is required
332            (depending on the presence and value of other parameters).
333          </td>
334        </tr>
335        <tr>
336          <td>out</td>
337          <td>
338            This attribute marks the parameter as an output to the
339            routine. This routine expects a named variable to be
340            passed to this parameter (if passed at all).
341          </td>
342        </tr>
343        <tr>
344          <td>private</td>
345          <td>
346            This attribute hides this parameter in IDLdoc output when
347            IDLdoc is run in "user" mode and marking it as "private"
348            when run in "developer" mode.
349          </td>
350        </tr>
351        <tr>
352          <td>required</td>
353          <td>
354            This attribute marks the parameter as required.
355          </td>
356        </tr>
357        <tr>
358          <td>type</td>
359          <td>
360            This atrribute defines the data type of the
361            parameter. Any string may be entered and is echoed in
362            the IDLdoc output. The special type "boolean" will cause
363            the calling syntax in IDLdoc output to use the IDL
364            online help syntax of prepending a "/" to the parameter
365            name.
366          </td>
367        </tr>
368      </table>
369     
370      <h2>File level comments</h2>
371     
372      <p>Some tags may appear in the comments for any routine in a
373      file because they document attributes of the file. These tags
374      are described below.</p>
375     
376      <table class="basic" cellspacing="0">
377        <tr>
378          <th>Tag</th>
379          <th>Description</th>
380        </tr>
381        <tr>
382          <td>file_comments</td>
383          <td>
384            Text following the tag is copied to the top of the file
385            in the IDLdoc output i.e. it is a comment on the file
386            and not the routine it appears in. If there are multiple
387            file_comments tags in the file, the comments will be
388            concatenated in the order they are present in the file.
389          </td>
390        </tr>
391        <tr>
392          <td>hidden_file</td>
393          <td>
394            Presence of this tag indicates this entire file should
395            be hidden in IDLdoc output.
396          </td>
397        </tr>
398        <tr>
399          <td>private_file</td>
400          <td>
401            Presence of this tag indicates this entire file should
402            be hidden in IDLdoc output if IDLdoc is run in "user"
403            mode, but shown when run in "developer" mode (the
404            default).
405          </td>
406        </tr>
407      </table>
408   
409      <h2>Examples</h2>
410     
411      For example, here's a sample class definition routine:
412     
413      <pre class="snippet">;+
414; Define the instance variables of the array_list.
415;
416; @file_comments An array_list is an object representing a variable
417;                length list of scalar elements of any single type.
418;                Array_lists support adding elements at the end of
419;                the vector only, but any element may be removed from
420;                the array_list. An iterator is provided for
421;                efficient and easy looping throught the elements of
422;                the array_list.
423;
424; @field data pointer to an array
425; @field cur_size the current size of the data in the array
426; @field max_size the maximum size of the data in the current array
427; @field type type code (as in SIZE function) for the elements in the
428;        array_list
429; @field sample_struct pointer to a structure if the type is
430;        "structure"
431; @field iterators IDL_Container for the iterators of this array_list
432;
433; @requires IDL 6.0
434;
435; @author Michael D. Galloy
436; @history Created September 26, 2003
437; @copyright RSI, 2003
438;-
439pro array_list__define
440    compile_opt idl2
441
442    define = { array_list, $
443        data:ptr_new(), $
444        cur_size:0L, $
445        max_size:0L, $
446        type:0L, $
447        sample_struct:ptr_new(), $
448        iterators:obj_new() $
449        }
450end</pre>       
451
452      Another example routine, this time a simple function with a positional parameter and keyword:
453
454      <pre class="snippet">;+
455; Returns [b, a] for a linear function y = a * x + b that sends
456; inRange[0] -> range[0] and inRange[1] -> range[1].
457;
458; @returns dblarr(2)
459; @param inRange {in}{required}{type=2 element numeric array} input
460;        range
461; @keyword range {in}{optional}{type=dblarr(2)}{default=[0.D, 1.D]}
462;          output range
463; @categories math, object graphics
464;-
465function linear_function, inRange, range=outRange
466    compile_opt idl2
467
468    i_outRange = n_elements(outRange) eq 0 $
469        ? [0.D, 1.D] $
470        : double(outRange)
471
472    scale = [i_outRange[0] * inRange[1] - i_outRange[1] * inRange[0], $
473        i_outRange[1] - i_outRange[0]] / (inRange[1] - inRange[0])
474    return, scale
475end</pre>
476
477      One more example, this time a function method with an output keyword.
478
479      <pre class="snippet">;+
480; Finds the value associated with the given key.
481;
482; @returns the value of the associated key or -1L if not found
483; @param key {in}{type=key type} key to look up
484; @keyword found {out}{optional}{type=boolean} true if value found for
485;          given key
486;-
487function hash_table::get, key, found=found</pre>
488
489      <h2>Directory overviews</h2>
490
491      <p>The "dir-overview" file in each directory of the library is
492      copied into the directory overview file. Much of the content of
493      the overview file is obtained from the PRO code files in the
494      directory, but this allows header content as an overview of the
495      all the files in the directory to be inserted at the top of the
496      directory overview file.</p>
497
498
499      <h2>Library overview</h2>
500
501      <p>The library overview file is a single file which is inserted
502      into the opening page of the IDLdoc output. This file is copied
503      verbatim into the IDLdoc output except for the following tag
504      which allows for comments on the contents of the directories
505      found in the library.</p>
506
507      <table class="basic" cellspacing="0">
508        <tr>
509          <th>Tag</th>
510          <th>Description</th>
511        </tr>
512        <tr>
513          <td>dir</td>
514          <td>
515            The text following this tag is the relative path
516            (web-style, always with a /) to a directory in the
517            library and a comment which is copied into a table in
518            the opening page of the IDLdoc output.
519           
520            <pre class="snippet">; @dir algorithms/math mathematical routines</pre>
521          </td>
522        </tr>
523      </table>
524   
525      <h2>Syntax of IDLdoc routine</h2>
526     
527      <p>Below is the IDLdoc generated documentation for the IDLdoc main routine.</p>
528
529      [% INCLUDE idldoc_syntax_filename %]
530
531      [% IF footer NE '' %]<div id="footer">[% INCLUDE footer %]</div>[% END %]
532
533      [% INCLUDE_TEMPLATE tagline_filename %]
534     
535    </div>
536   
537  </body>
538</html>
Note: See TracBrowser for help on using the repository browser.