source: trunk/Documentation/idldoc/docs/idldoc-dev-help.html @ 69

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

debug + new xxx
File size: 33.9 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 2.0 on Sat Mar 11 21:40:01 2006 -->
18
19<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
20  <head>
21    <title>IDLdoc Developer's Help (IDLdoc project documentation)</title>
22
23   
24    <style type="text/css" media="all">
25         
26/* CSS for all files which appear in the "main" viewing area: overview,
27   directory overviews, warnings, index, search, pro files, source
28   code, help, and etc files. */
29
30/* Link styles --------------------------------------------------------------- */
31
32a { text-decoration: none; }
33
34a:link, a:visited { 
35  color: #660000; 
36  border-bottom: 1px dotted #C0C0F0;   
37}
38
39a:hover, a:focus { 
40  color: #993333; 
41  background: #FFFFCC; 
42  border-bottom: 1px dotted #303099; 
43}
44
45
46/* Main styles --------------------------------------------------------------- */
47
48body {
49  margin: 0;
50  padding: 0;
51  font-size: 10pt;
52  font-family: Verdana, Helvetica, Arial, sans-serif;
53  background-color: #FFFFFF;
54}
55
56p {
57  margin-top: 0.5em;
58  margin-bottom: 0;
59}
60
61#container { margin: 1em; }
62
63code.section { white-space: pre; }
64
65pre.snippet {
66  margin-left: 5%;
67  background: #F0F0F0;
68  border: 1px dashed #999999;
69  width: 43em;
70  padding: 0.5em 0.5em 0.5em 0.5em;
71  white-space: pre;
72}
73
74/* Navbar styles ------------------------------------------------------------- */
75
76#navbar_title {
77  color: #000033;
78  background-color: #F0F0FF;
79  font-family: Arial, Helvetica, sans-serif;
80  padding: 20px 30px;
81  border-bottom: 1px solid #000033;
82}
83
84#navbar_title * {
85  margin: 0;
86  padding: 0;
87}
88
89#navbar_title h1 {
90  letter-spacing: 0.1em;
91  font-variant: small-caps;
92  font-size: 250%;
93  text-indent: -1em;
94  padding-left: 1em; 
95}
96
97#navbar_title h2 {
98  font-size: 110%;
99  font-weight: normal;
100  color: #333399;
101}
102
103#main_navbar table {
104  width: 100%;
105  border-bottom: 1px solid #666699;
106}
107
108#main_navbar td {
109  background: #CCCCFF;
110  font-size: 80%;
111  font-weight: bold;
112  font-family: Arial, Helvetica, sans-serif;
113  border-top: 3px solid #CCCCFF;
114  border-bottom: 3px solid #CCCCFF;
115  padding-left: 6px;
116  padding-right: 6px;
117  margin: 0;
118}
119
120#main_navbar td#selected {
121  background: #CCCCFF;
122  font-size: 80%;
123  font-weight: bold;
124  font-family: Arial, Helvetica, sans-serif;
125  border-top: 3px solid #333399;
126  border-bottom: 3px solid #CCCCFF;
127  padding-left: 6px;
128  padding-right: 6px;
129  margin: 0;
130}
131
132#main_navbar td#flexible {
133  width: 100%;
134  text-align: right;
135  padding-right: 1em;
136  background: #CCCCFF;
137  font-size: 70%;
138  font-weight: normal;
139  font-family: Arial, Helvetica, sans-serif;
140  text-transform: uppercase;
141  border-top: 3px solid #CCCCFF;
142  border-bottom: 3px solid #CCCCFF;
143}
144
145#main_navbar a:link, #main_navbar a:visited { color: #660000; border: 0; }
146
147#main_navbar a:hover, #main_navbar a:focus {
148  color: #FFFF66;
149  background: #CCCCFF;
150  border-bottom: 1px none #606099; 
151  border: 0;
152}
153
154#secondary_navbar {
155  font-size: 80%;
156  font-weight: normal;
157  font-family: Arial, Helvetica, sans-serif;
158  margin-top: 4px;
159  margin-left: 20px;
160  white-space: nowrap;
161}
162
163
164/* Tagline and footer styles ------------------------------------------------- */
165
166div#tagline {
167  margin-top: 6px;
168  border-top: 1px dotted lightsteelblue;
169  padding-top: 6px;
170  font-size: 66%;
171  font-style: italic;
172}
173
174div#footer {
175  margin-top: 6px;
176  border-top: 1px dotted lightsteelblue;
177  padding-top: 6px;
178  font-size: 66%;
179  font-style: italic;
180}
181
182/* Basic data presenation styles -------------------------------------------- */
183
184.index_letter { 
185  font-size: 300%;
186  font-weight: bold;
187  color: #000066; 
188  margin: 0.5em 0 0 -0.1em;
189}
190
191h1, h2, h3, h4 {
192  font-weight: normal;
193  color: #3333CC;
194}
195
196h1 {
197  padding-top: 0.75em;
198  font-size: 160%;
199}
200
201h2 {
202  padding-top: 1em;
203  font-size: 120%;
204  }
205
206h3 {
207  padding-top: 0.75em;
208  margin-bottom: 0.25em;
209  font-size: 100%;
210}
211
212h4 {
213  padding: 0;
214  margin: 0.5em 0 0 0;
215  font-size: 80%;
216}
217
218table.basic {
219  empty-cells: show;
220  margin: 1.5em 1em 0 1em;
221  border: 1px dotted #CFCFFF;
222  font-size: 80%;
223}
224
225table.basic th {
226  background-color: #F0F0FF;
227  font-weight: bold;
228  text-align: left;
229  padding: 4px 1em 4px 4px;
230  border-bottom: 1px dotted #666699;
231}
232
233table.basic td {
234  vertical-align: top;
235  padding: 4px 1em 4px 4px;
236}
237
238dd {
239  margin-bottom: 0.25em;
240  font-size: 80%;
241}
242
243
244/* Warnings styles ----------------------------------------------------------- */
245
246
247#todo dl, #bugs dl { 
248  margin: 0 0 0 1.5em;
249  font-size: 80%;
250}
251
252#todo dd, #bugs dd { 
253  margin-left: 3em; 
254  font-size: 100%;
255}
256
257#undoc table, #obsolete table, #statistics table {
258  width: 80%;
259  margin-left: 2em;
260}
261
262#undoc td, #obsolete td, #statistics td { 
263  padding: 0 0 0 0;
264  font-size: 80%;
265  white-space: nowrap;
266}
267
268#undoc td.docroutine, #obsolete td.obsroutine, #statistics td.statroutine { width: 50%; }
269
270#undoc td.docstat, #statistics td.stat { 
271  width: 50%;
272  text-align: right;
273}
274
275#undoc td.partialdoc, #statistics td.caution { color: #CC6600; }
276
277#undoc td.notdoc, #statistics td.warning { color: #993333; }
278
279/* File + routine styles ----------------------------------------------------- */
280
281h1.directory { 
282  padding: 1em 0 0 0;
283  margin: 0;
284  font-size: 66%;
285}
286
287h1.directory a { border-bottom: 0; }
288
289h2.pro_file { 
290  padding: 0;
291  margin: 0;
292  font-size: 140%;
293}
294
295div#file_attr {
296  padding: 0 1em 0 1em;
297  margin: 1em;
298  background: #F6F6F6;
299  border: 1px dotted #999999;
300}
301
302div#file_attr dt {
303  font-size: 80%;
304  font-weight: bold;
305}
306
307div#file_attr dd {
308  font-size: 80%;
309}
310
311div#class_diagram { 
312  padding: 1em 0 1em 0; 
313  white-space: pre;
314  font-family: 'Courier New';
315}
316
317table#sav_attr { 
318  font-size: 90%; 
319  margin: 1em; 
320  padding: 1em 1em 1em 1em;
321  background: #F6F6F6;
322  border: 1px dotted #999999;
323}
324
325table#sav_attr th { text-align: left; }
326
327table#sav_attr td { vertical-align: top; padding-right: 2em; }
328
329table#sav_attr td.value { width: 20em; padding-right: 0em; font-style: italic; }
330
331p.sav_warning { margin-left: 4em; font-family: 80%; }
332
333table.variables { 
334  font-family: 'Courier New', monospace; 
335  font-size: 80%; 
336  text-indent: -2em; 
337  padding-left: 2em; 
338}
339
340table.variables td.image { width: 64px; }
341
342div#file_comments { 
343  margin: 2em;
344  font-size: 80%;
345}
346
347
348div.field_summary {
349  padding: 0 1em 0 1em;
350  margin: 1em;
351  background: #FFFFF0;
352  border: 1px dotted #C0C000;
353}
354
355div#routine_summary { 
356  padding: 0 1em 0 1em;
357  margin: 1em;
358  background: #F0F0FF;
359  border: 1px dotted #9999FF;
360}
361
362div.field_summary h2, div#routine_summary h2 { 
363  padding: 0.5em 0 0 0;
364  margin: 0;
365}
366
367div.field_summary table, div.field_summary p { 
368  margin: 1em 1em;
369}
370
371div.field_summary td.name { 
372  vertical-align: top;
373  padding-bottom: 0.25em;
374  color: #3333CC;
375}
376
377div.field_summary span.field_type { 
378  font-weight: normal;
379  font-size: 80%;
380  color: black;
381}
382
383div.field_summary td.comments { 
384  vertical-align: top;
385  padding-left: 2em;
386  font-size: 80%;
387}
388
389p.commaList { 
390  margin: 1em 1em 1em 1em;
391}
392
393span.warning { 
394  color: #CC6633;
395  font-weight: bold;
396  font-size: 66%;
397  text-transform: uppercase;
398}
399
400span.categories { 
401  color: #006633;
402  font-weight: bold;
403  font-size: 66%;
404  text-transform: uppercase;
405}
406
407span.undoc { 
408  color: #FF6633;
409  font-weight: bold;
410  font-size: 80%;
411  text-transform: uppercase;
412}
413
414span.attr { 
415  color: #006633;
416  font-weight: bold;
417  font-size: 80%;
418  text-transform: uppercase;
419}
420
421span.value { 
422  color: #006633;
423  font-weight: normal;
424  text-transform: none;
425}
426
427a.top { 
428  font-weight: bold;
429  font-size: 66%;
430  text-transform: uppercase;
431  float: right;
432}
433
434span.result { 
435  font-family: Verdana, Arial, Helvetica, sans-serif;
436  font-style: italic;
437  font-size: 80%;
438}
439
440div#routine_summary p, div.routine_details p.header { 
441  padding-top: 0.5em;
442  margin-left: 1.5em;
443  text-indent: -1.5em;
444  font-family: 'Courier New', monospace;
445}
446
447div.routine_details { 
448  padding: 0.5em 1em 0.5em 1em;
449  margin: 1em;
450  border: 1px dotted #CCCCCC;
451}
452
453div.routine_details h2 { 
454  padding-top: 0;
455  margin-top: 0;
456}
457
458div.routine_details div.value { 
459  margin: 0 1em 0 1em;
460  font-size: 80%;
461}
462
463div.routine_details div.comments { 
464  font-size: 80%;
465  margin: 0.75em 1em 1em 1em;
466}
467
468div.routine_details div.preformat { 
469  white-space: pre;
470}
471
472table.statistics { 
473  font-size: 80%;
474  margin-left: 1em;
475}
476
477table.statistics td { 
478  padding: 0 2em 0 0;
479}
480
481/* Overview styles ----------------------------------------------------------- */
482
483div.overview { 
484  width: 100%;
485  margin-top: 1em;
486  clear: both;
487}
488
489div.overview table {
490  empty-cells: show;
491  font-size: 90%;
492  margin: 1em 1em 1em 1em;
493  padding: 1em 0.5em 1em 0.5em;
494  background: #F6F6F6;
495  border: 1px dotted #999999;
496}
497
498div.overview td {
499  padding: 3px 1em 3px 1em;
500}
501
502div.overview td.dir {
503  width: 1%;
504  vertical-align: top;
505  text-align: right;
506  padding-right: 1em;
507}
508
509
510/* Navigation list styles for tree structures -------------------------------- */
511
512#tree {
513  text-align: left;
514  font-size: 90%;
515  margin: 0.75em 0 0.75em 0;
516  padding: 0;
517}
518
519#tree ul {
520  text-align: left;
521  margin: 0;
522  padding: 0;
523}
524
525#tree li {
526  margin: 0 0 0 15px;
527  padding: 0;
528  list-style-type: none;
529}
530
531#tree .symbols {
532  float: left;
533  width: 12px;
534  height: 1em;
535  padding-left: 4px;
536  background-position: 0 100%;
537  background-repeat: no-repeat;
538}
539
540/* Search styles ------------------------------------------------------------- */
541
542input.writein { 
543  padding-left: 0.5em;
544  border: 1px solid #CCCCCC;
545  font-family: 'Courier New';
546  background: #FFFFF3;
547}
548
549#search form { 
550  margin-left: 2em;
551}
552
553#search table { 
554  margin: 1em 1em 0 2em;
555  padding: 1em 2em 1em 2em;
556  background: #F6F6F6;
557  border: 1px dotted #999999;
558}
559
560#search tr { 
561  text-align: center;
562}
563
564#search td { 
565  font-size: 80%; 
566  text-align: left;
567}
568
569#search td * { 
570  vertical-align: middle;
571}
572
573#search p { 
574  font-size: 66%;
575  margin: 0 3em 2em 3em;
576}
577
578/* Help styles --------------------------------------------------------------- */
579
580div.toc { 
581  padding: 0 1em 0 1em;
582  margin: 1em;
583  background: #F0F0FF;
584  border: 1px dotted #9999FF; 
585  width: 19em;
586}
587
588div.right { 
589  float: right;
590  width: 22em;
591}
592
593ol.toc { 
594  list-style-type: upper-roman;
595}
596
597ol.toc ol { 
598  padding-left: 3em;
599  margin-left: 0;
600  list-style-type: lower-alpha;
601}
602
603dl.variables dt { font-size: 80%; }
604dl.variables dd { margin-bottom: 0.5em; }
605
606    </style>   
607    <style type="text/css" media="print">
608         #navbar_title { 
609  background-color: #FFFFFF; 
610}
611
612#main_navbar td {
613  background: #FFFFFF;
614  border-top: 0.25em solid #FFFFFF;
615  border-bottom: 0.25em solid #FFFFFF;
616}
617
618#main_navbar td#selected {
619  background: #FFFFFF;
620  border-top: 0.25em solid #333399;
621  border-bottom: 0.25em solid #FFFFFF;
622}
623
624#main_navbar td#flexible {
625  background: #FFFFFF;
626  border-top: 0.25em solid #FFFFFF;
627  border-bottom: 0.25em solid #FFFFFF;
628}
629
630#secondary_navbar {
631  display: none;
632}
633
634    </style>
635   
636
637    <script type="text/javascript">
638      function setTitle() {
639        parent.document.title="IDLdoc Developer's Help (IDLdoc project documentation)";
640      }
641    </script>
642  </head>
643
644
645  <body onload="setTitle();">
646
647    <div id="navbar_title">
648  <h1>IDLdoc project documentation</h1>
649  <h2>"The IDL code documentation project documentation"</h2>
650</div>
651
652
653
654    <div id="container">
655
656      <h1>IDLdoc developer's guide</h1>
657
658      <p>This guide discusses how to mark up IDL pro code in order to
659      insert more information into IDLdoc's output.</p>
660
661      <p>Comments on the routine and file level are placed between
662      ";+" and ";-" lines before a routine in IDL source code. Content
663      between these lines is copied verbatim into the IDLdoc output
664      for the routine it appears before with the exception of the
665      @-preceded "tags" listed in tables below. Once an @ appears in
666      the comments, IDLdoc processes all remaining lines of the
667      comments as tags. To place a non-tag defining "@" in your
668      comments, escape it with a "\", as in
669      "email_address\@rsinc.com".</p>
670
671      <p>In the following example, the @author tag is used to indicate
672      an author of the code. The second "@" is escaped to allow its
673      literal use in the email address:</p>
674
675        <pre class="snippet">; @author Michael Galloy, mgalloy\@rsinc.com</pre>
676
677      <h2>Routine level comments</h2>
678
679      <p>There are many tags which describe an individual
680      routine. Each tag name appears after an "@" sign as the first
681      non-whitespace character after the ;. The tags are described
682      below.</p>
683
684      <table class="basic" cellspacing="0">
685        <tr>
686          <th>Tag</th>
687          <th>Description</th>
688        </tr>
689        <tr>
690          <td>abstract</td>
691          <td>
692            Presence of the this tag indicates this method is
693            abstract. This is intended for use with methods of a class
694            which are not intended to be called, but are only provided
695            as documenting an interface that a subclass will override.
696          </td>
697        </tr>
698        <tr>
699          <td>author</td>
700          <td>
701            Text following this tag appears in a list of attributes
702            of the routine marked as "Author."
703          </td>
704        </tr>
705        <tr>
706          <td>bugs</td>
707          <td>
708            Text that follows this tag is copied into a bug
709            attribute of the routine and placed in a library wide
710            listing which documents known failings of routines.
711          </td>
712        </tr>
713        <tr>
714          <td>categories</td>
715          <td>
716            Text following this tag is used as a comma separated list
717            of categories of the routine. The syntax is:
718
719            <pre class="snippet">; @categories math, input/output</pre>
720
721            Category names are case-sensitive and may contain any
722            characters except commas (though whitespace at the
723            beginning and end will be removed).
724          </td>
725        </tr>
726        <tr>
727          <td>copyright</td>
728          <td>
729            Text following this tag appears in a list of attributes
730            of the routine marked as "Copyright."
731          </td>
732        </tr>
733        <tr>
734          <td>customer_id</td>
735          <td>
736            Text following this tag appears in a list of attributes
737            of the routine marked as "Customer ID."
738          </td>
739        </tr>
740        <tr>
741          <td>examples</td>
742          <td>
743            Text following this tag is copied into an examples
744            attribute of the routine; it is intended to have
745            example code of using the routine.
746          </td>
747        </tr>
748        <tr>
749          <td>field</td>
750          <td>
751            For routines in files that end in "__define", this
752            provides documentation of a member variable of a
753            class/structure. The syntax is
754       
755            <pre class="snippet">; @field field_name comment</pre>
756       
757            where "field" matches one of the structure field names
758            of the structure type/class being defined.
759          </td>
760        </tr>
761        <tr>
762          <td>hidden</td>
763          <td>
764            Presence of this tag hides this routine in IDLdoc
765            output.
766          </td>
767        </tr>
768        <tr>
769          <td>history</td>
770          <td>
771            Text following this tag is copied into a history
772            attribute of the routine; it is intended to have a
773            history of the creators and modifiers of the source
774            code of the routine.
775          </td>
776        </tr>
777        <tr>
778          <td>inherits</td>
779          <td>
780            Obsolete. Intended to provide the parent class of the
781            documented class, but this is automatically handled by
782            IDLdoc now (as long as class definitions are in files
783            that end "__define").
784          </td>
785        </tr>
786        <tr>
787          <td>keyword</td>
788          <td>
789            This tag documents a single keyword parameter to the
790            routine. This syntax is
791       
792            <pre class="snippet">; @keyword keyword_name attributes comment</pre>
793       
794            Attributes further describe keyword and detailed in
795            the section below. The comment may be an text and is
796            copied into the IDLdoc output.
797          </td>
798        </tr>
799        <tr>
800          <td>obsolete</td>
801          <td>
802            Presence of this tag marks the routine as obsolete.
803          </td>
804        </tr>
805        <tr>
806          <td>param</td>
807          <td>
808            This tag documents a single keyword parameter to the
809            routine. This syntax is
810       
811            <pre class="snippet">; @param keyword_name attributes comment</pre>
812       
813            Attributes further describe keyword and detailed in
814            the section below. The comment may be an text and is
815            copied into the IDLdoc output.
816          </td>
817        </tr>
818        <tr>
819          <td>pre</td>
820          <td>
821            Text following this tag will be copied to a pre
822            attribute of the routine; it is intended to give
823            conditions the routine assumes to be true before it
824            runs.
825          </td>
826        </tr>
827        <tr>
828          <td>post</td>
829          <td>
830            Text following this tag will be copied to a post
831            attribute of the routine; it is intended to give
832            conditions the routine assumes to be true after it
833            runs.
834          </td>
835        </tr>
836        <tr>
837          <td>private</td>
838          <td>
839            Presence of this tag will hide this routine in IDLdoc
840            output if IDLdoc is run in "user" mode.
841          </td>
842        </tr>
843        <tr>
844          <td>requires</td>
845          <td>
846            Text following this tag is copied into the "Requires"
847            attribute of the routine; it is intended to provide
848            the version of IDL required to run the routine. For
849            example,
850       
851            <pre class="snippet">; @requires IDL 6.2</pre>
852       
853            will simply cause "IDL 6.2" to appear in the
854            "Requires" attribute.
855          </td>
856        </tr>
857        <tr>
858          <td>restrictions</td>
859          <td>
860            Text following this tag is copied into the
861            "Restrictions" attribute of the routine; it is
862            intended to provide any restrictions on the use of the
863            routine.
864          </td>
865        </tr>
866        <tr>
867          <td>returns</td>
868          <td>
869            Text following this tag is copied into the "Returns"
870            attribute of the routine; it is intended to provide
871            information about return value of a function.
872          </td>
873        </tr>
874        <tr>
875          <td>todo</td>
876          <td>
877            This tag places an item in a library-wide list of todo
878            items. The text following the tag is copied into this list
879            along with the routine it appears in it.
880          </td>
881        </tr>
882        <tr>
883          <td>uses</td>
884          <td>
885            Text following this tag is placed in a uses attribute of
886            the routine; it is intended to list routines that this
887            routine calls.
888          </td>
889        </tr>
890        <tr>
891          <td>version</td>
892          <td>
893            Text following this tag is placed in a version attribute
894            of the routine; it is intended to give a version
895            name/number of the routine.
896          </td>
897        </tr>
898      </table>
899
900      <p>For each positional parameters or keyword tag additional
901      attributes may be added in curly braces. For example,</p>
902       
903      <pre class="snippet">; @param x {in}{required}{type=lonarr} x-axis data</pre>
904       
905      <p>The attributes are described below.</p>
906
907      <table class="basic" cellspacing="0">
908        <tr>
909          <th>Attribute</th>
910          <th>Description</th>
911        </tr>
912        <tr>
913          <td>default</td>
914          <td>
915            This atrribute defines the default value of the
916            parameter. Any string may be entered and is echoed in the
917            IDLdoc output.
918          </td>
919        </tr>
920        <tr>
921          <td>hidden</td>
922          <td>
923            This attribute hides this parameter in IDLdoc output.
924          </td>
925        </tr>
926        <tr>
927          <td>in</td>
928          <td>
929            This attribute marks the parameter as an input to the
930            routine.
931          </td>
932        </tr>
933        <tr>
934          <td>optional</td>
935          <td>
936            This attribute marks the parameter as optional; the
937            routine does not always need this parameter, although
938            there might be cases where the parameter is required
939            (depending on the presence and value of other parameters).
940          </td>
941        </tr>
942        <tr>
943          <td>out</td>
944          <td>
945            This attribute marks the parameter as an output to the
946            routine. This routine expects a named variable to be
947            passed to this parameter (if passed at all).
948          </td>
949        </tr>
950        <tr>
951          <td>private</td>
952          <td>
953            This attribute hides this parameter in IDLdoc output when
954            IDLdoc is run in "user" mode and marking it as "private"
955            when run in "developer" mode.
956          </td>
957        </tr>
958        <tr>
959          <td>required</td>
960          <td>
961            This attribute marks the parameter as required.
962          </td>
963        </tr>
964        <tr>
965          <td>type</td>
966          <td>
967            This atrribute defines the data type of the
968            parameter. Any string may be entered and is echoed in
969            the IDLdoc output. The special type "boolean" will cause
970            the calling syntax in IDLdoc output to use the IDL
971            online help syntax of prepending a "/" to the parameter
972            name.
973          </td>
974        </tr>
975      </table>
976
977      <h2>File level comments</h2>
978
979      <p>Some tags may appear in the comments for any routine in a
980      file because they document attributes of the file. These tags
981      are described below.</p>
982
983      <table class="basic" cellspacing="0">
984        <tr>
985          <th>Tag</th>
986          <th>Description</th>
987        </tr>
988        <tr>
989          <td>file_comments</td>
990          <td>
991            Text following the tag is copied to the top of the file
992            in the IDLdoc output i.e. it is a comment on the file
993            and not the routine it appears in. If there are multiple
994            file_comments tags in the file, the comments will be
995            concatenated in the order they are present in the file.
996          </td>
997        </tr>
998        <tr>
999          <td>hidden_file</td>
1000          <td>
1001            Presence of this tag indicates this entire file should
1002            be hidden in IDLdoc output.
1003          </td>
1004        </tr>
1005        <tr>
1006          <td>private_file</td>
1007          <td>
1008            Presence of this tag indicates this entire file should
1009            be hidden in IDLdoc output if IDLdoc is run in "user"
1010            mode, but shown when run in "developer" mode (the
1011            default).
1012          </td>
1013        </tr>
1014      </table>
1015
1016      <h2>Examples</h2>
1017
1018      For example, here's a sample class definition routine:
1019
1020      <pre class="snippet">;+
1021; Define the instance variables of the array_list.
1022;
1023; @file_comments An array_list is an object representing a variable
1024;                length list of scalar elements of any single type.
1025;                Array_lists support adding elements at the end of
1026;                the vector only, but any element may be removed from
1027;                the array_list. An iterator is provided for
1028;                efficient and easy looping throught the elements of
1029;                the array_list.
1030;
1031; @field data pointer to an array
1032; @field cur_size the current size of the data in the array
1033; @field max_size the maximum size of the data in the current array
1034; @field type type code (as in SIZE function) for the elements in the
1035;        array_list
1036; @field sample_struct pointer to a structure if the type is
1037;        "structure"
1038; @field iterators IDL_Container for the iterators of this array_list
1039;
1040; @requires IDL 6.0
1041;
1042; @author Michael D. Galloy
1043; @history Created September 26, 2003
1044; @copyright RSI, 2003
1045;-
1046pro array_list__define
1047    compile_opt idl2
1048
1049    define = { array_list, $
1050        data:ptr_new(), $
1051        cur_size:0L, $
1052        max_size:0L, $
1053        type:0L, $
1054        sample_struct:ptr_new(), $
1055        iterators:obj_new() $
1056        }
1057end</pre>       
1058
1059      Another example routine, this time a simple function with a positional parameter and keyword:
1060
1061      <pre class="snippet">;+
1062; Returns [b, a] for a linear function y = a * x + b that sends
1063; inRange[0] -> range[0] and inRange[1] -> range[1].
1064;
1065; @returns dblarr(2)
1066; @param inRange {in}{required}{type=2 element numeric array} input
1067;        range
1068; @keyword range {in}{optional}{type=dblarr(2)}{default=[0.D, 1.D]}
1069;          output range
1070; @categories math, object graphics
1071;-
1072function linear_function, inRange, range=outRange
1073    compile_opt idl2
1074
1075    i_outRange = n_elements(outRange) eq 0 $
1076        ? [0.D, 1.D] $
1077        : double(outRange)
1078
1079    scale = [i_outRange[0] * inRange[1] - i_outRange[1] * inRange[0], $
1080        i_outRange[1] - i_outRange[0]] / (inRange[1] - inRange[0])
1081    return, scale
1082end</pre>
1083
1084      One more example, this time a function method with an output keyword.
1085
1086      <pre class="snippet">;+
1087; Finds the value associated with the given key.
1088;
1089; @returns the value of the associated key or -1L if not found
1090; @param key {in}{type=key type} key to look up
1091; @keyword found {out}{optional}{type=boolean} true if value found for
1092;          given key
1093;-
1094function hash_table::get, key, found=found</pre>
1095
1096      <h2>Directory overviews</h2>
1097
1098      <p>The "dir-overview" file in each directory of the library is
1099      copied into the directory overview file. Much of the content of
1100      the overview file is obtained from the PRO code files in the
1101      directory, but this allows header content as an overview of the
1102      all the files in the directory to be inserted at the top of the
1103      directory overview file.</p>
1104
1105
1106      <h2>Library overview</h2>
1107
1108      <p>The library overview file is a single file which is inserted
1109      into the opening page of the IDLdoc output. This file is copied
1110      verbatim into the IDLdoc output except for the following tag
1111      which allows for comments on the contents of the directories
1112      found in the library.</p>
1113
1114      <table class="basic" cellspacing="0">
1115        <tr>
1116          <th>Tag</th>
1117          <th>Description</th>
1118        </tr>
1119        <tr>
1120          <td>dir</td>
1121          <td>
1122            The text following this tag is the relative path
1123            (web-style, always with a /) to a directory in the
1124            library and a comment which is copied into a table in
1125            the opening page of the IDLdoc output.
1126       
1127            <pre class="snippet">; @dir algorithms/math mathematical routines</pre>
1128          </td>
1129        </tr>
1130      </table>
1131
1132      <h2>Syntax of IDLdoc routine</h2>
1133
1134      <p>Below is the IDLdoc generated documentation for the IDLdoc main routine.</p>
1135
1136        <div class="routine_details" id="_idldoc">
1137
1138          <h2><a class="top" href="#container">top</a>idldoc</h2>
1139       
1140          <p class="header">
1141            idldoc, <a href="#_idldoc_keyword_root">root</a>=<span class="result">string</span>[, <a href="#_idldoc_keyword_output">output</a>=<span class="result">string</span>][, <a href="#_idldoc_keyword_overview">overview</a>=<span class="result">string</span>][, <a href="#_idldoc_keyword_footer">footer</a>=<span class="result">string</span>][, <a href="#_idldoc_keyword_log_file">log_file</a>=<span class="result">string</span>][, /<a href="#_idldoc_keyword_user">user</a>][, /<a href="#_idldoc_keyword_quiet">quiet</a>][, /<a href="#_idldoc_keyword_silent">silent</a>][, /<a href="#_idldoc_keyword_embed">embed</a>][, /<a href="#_idldoc_keyword_nonavbar">nonavbar</a>][, <a href="#_idldoc_keyword_title">title</a>=<span class="result">string</span>][, <a href="#_idldoc_keyword_subtitle">subtitle</a>=<span class="result">string</span>][, /<a href="#_idldoc_keyword_statistics">statistics</a>][, <a href="#_idldoc_keyword_n_warnings">n_warnings</a>=<span class="result">variable</span>][, /<a href="#_idldoc_keyword_browse_routines">browse_routines</a>][, /<a href="#_idldoc_keyword_preformat">preformat</a>][, /<a href="#_idldoc_keyword_assistant">assistant</a>]</p>
1142       
1143          <div class="comments">Calling routine for IDLdoc.</div>
1144
1145            <h3>Keywords</h3>
1146           
1147            <h4 id="_idldoc_keyword_root">root&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1148              <span class="attr">in</span>
1149              <span class="attr">required</span>
1150              <span class="attr">type:</span> <span class="value">string</span>
1151            </h4>
1152       
1153            <div class="comments"> root directory for IDLdoc's
1154            recursive search for .pro files.  IDLdoc will find any
1155            files with the '.pro' suffix and include them in its file
1156            listings.  Only directories with '.pro' files in them are
1157            included in the directory listings.</div>
1158           
1159            <h4 id="_idldoc_keyword_output">output&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1160              <span class="attr">in</span>
1161              <span class="attr">optional</span>
1162              <span class="attr">type:</span> <span class="value">string</span>
1163              <span class="attr">default:</span> <span class="value">same as root</span>
1164            </h4>
1165       
1166            <div class="comments">
1167            directory in which to create the HTML output and possible
1168            subdirectories</div>
1169           
1170            <h4 id="_idldoc_keyword_overview">overview&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1171              <span class="attr">in</span>
1172              <span class="attr">optional</span>
1173              <span class="attr">type:</span> <span class="value">string</span>
1174            </h4>
1175       
1176            <div class="comments"> filepath to a file containing the
1177            summary of the package information about each directory in
1178            the package.</div>
1179           
1180            <h4 id="_idldoc_keyword_footer">footer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1181              <span class="attr">in</span>
1182              <span class="attr">optional</span>
1183              <span class="attr">type:</span> <span class="value">string</span>
1184            </h4>
1185       
1186            <div class="comments"> filename for a footer to be placed
1187            at the bottom of files; this file can contain any valid
1188            HTML</div>
1189           
1190            <h4 id="_idldoc_keyword_log_file">log_file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1191              <span class="attr">in</span>
1192              <span class="attr">optional</span>
1193              <span class="attr">type:</span> <span class="value">string</span>
1194            </h4>
1195       
1196            <div class="comments"> set to a filename of a file to
1197            contain the error messages generated by the IDLdoc run;
1198            useful for automated runs of IDLdoc</div>
1199           
1200            <h4 id="_idldoc_keyword_user">user&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1201              <span class="attr">in</span>
1202              <span class="attr">optional</span>
1203              <span class="attr">type:</span> <span class="value">boolean</span>
1204            </h4>
1205       
1206            <div class="comments"> set to create a listing appropriate
1207            for <em>users</em> of the given library hierarchy; the
1208            default is to create documentation suited to developers.
1209            If set private routines are not shown in the
1210            documentation.</div>
1211           
1212            <h4 id="_idldoc_keyword_quiet">quiet&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1213              <span class="attr">in</span>
1214              <span class="attr">optional</span>
1215              <span class="attr">type:</span> <span class="value">boolean</span>
1216            </h4>
1217       
1218            <div class="comments"> if set, print only
1219            warnings</div>
1220           
1221            <h4 id="_idldoc_keyword_silent">silent&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1222              <span class="attr">in</span>
1223              <span class="attr">optional</span>
1224              <span class="attr">type:</span> <span class="value">boolean</span>
1225            </h4>
1226       
1227            <div class="comments"> if set, print no
1228            messages</div>
1229           
1230            <h4 id="_idldoc_keyword_embed">embed&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1231              <span class="attr">in</span>
1232              <span class="attr">optional</span>
1233              <span class="attr">type:</span> <span class="value">boolean</span>
1234            </h4>
1235       
1236            <div class="comments"> if set, embeds style sheet in each
1237            HTML document; if this is not set, each HTML file will be
1238            looking for the cascading style sheet idldoc.css in the
1239            directory specified for the ROOT keyword</div>
1240           
1241            <h4 id="_idldoc_keyword_nonavbar">nonavbar&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1242              <span class="attr">in</span>
1243              <span class="attr">optional</span>
1244              <span class="attr">type:</span> <span class="value">boolean</span>
1245            </h4>
1246       
1247            <div class="comments"> set to exclude the
1248            navigation bar at the top of each page</div>
1249           
1250            <h4 id="_idldoc_keyword_title">title&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1251              <span class="attr">in</span>
1252              <span class="attr">optional</span>
1253              <span class="attr">type:</span> <span class="value">string</span>
1254              <span class="attr">default:</span> <span class="value">Research Systems</span>
1255            </h4>
1256       
1257            <div class="comments"> title of
1258            the library</div>
1259           
1260            <h4 id="_idldoc_keyword_subtitle">subtitle&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1261              <span class="attr">in</span>
1262              <span class="attr">optional</span>
1263              <span class="attr">type:</span> <span class="value">string</span>
1264              <span class="attr">default:</span> <span class="value">IDL version</span>
1265            </h4>
1266       
1267            <div class="comments"> subtitle of
1268            the library</div>
1269           
1270            <h4 id="_idldoc_keyword_statistics">statistics&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1271              <span class="attr">in</span>
1272              <span class="attr">optional</span>
1273              <span class="attr">type:</span> <span class="value">boolean</span>
1274            </h4>
1275       
1276            <div class="comments"> set to calculate several
1277            McCabe statistics for each routine</div>
1278           
1279            <h4 id="_idldoc_keyword_n_warnings">n_warnings&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1280              <span class="attr">out</span>
1281              <span class="attr">optional</span>
1282              <span class="attr">type:</span> <span class="value">integer</span>
1283            </h4>
1284       
1285            <div class="comments"> set to a named variable to
1286            contain the total number of warnings issued during the run</div>
1287           
1288            <h4 id="_idldoc_keyword_browse_routines">browse_routines&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1289              <span class="attr">in</span>
1290              <span class="attr">optional</span>
1291              <span class="attr">type:</span> <span class="value">boolean</span>
1292            </h4>
1293       
1294            <div class="comments"> set to include a frame
1295            to browse through the routines of the current file</div>
1296           
1297            <h4 id="_idldoc_keyword_preformat">preformat&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1298              <span class="attr">in</span>
1299              <span class="attr">optional</span>
1300              <span class="attr">type:</span> <span class="value">boolean</span>
1301            </h4>
1302       
1303            <div class="comments"> set to produce output that
1304            will look like it does in the code files (line for line)</div>
1305           
1306            <h4 id="_idldoc_keyword_assistant">assistant&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1307              <span class="attr">in</span>
1308              <span class="attr">optional</span>
1309              <span class="attr">type:</span> <span class="value">boolean</span>
1310            </h4>
1311       
1312            <div class="comments"> set to produce output for the
1313            IDL assistant help system instead of optimized for a web browser
1314            </div>
1315                 
1316          <h3>Examples</h3><div class="value"> To run IDLdoc, try:
1317            <center><code>idldoc, root='C:\mycode'</code></center>
1318            where C:\mycode is the root of a directory tree containing IDL
1319            .pro files.
1320            </div>
1321
1322          <h3>Version history</h3>
1323
1324          <h4>Author</h4><div class="value"> Michael D. Galloy</div>
1325         
1326          <h4>Copyright</h4><div class="value"> RSI, 2002</div>
1327         
1328          <h3>Other attributes</h3>
1329         
1330          <h4>Requires IDL version</h4><div class="value"> IDL 6.0</div>
1331       
1332        </div>
1333       
1334
1335
1336     
1337
1338      <div id="tagline">Produced by IDLdoc 2.0 on Sat Mar 11 21:40:01 2006.</div>
1339
1340    </div>
1341
1342  </body>
1343</html>
Note: See TracBrowser for help on using the repository browser.