source: trunk/SRC/Documentation/idldoc_html_output/idldoc-dev-help.html @ 109

Last change on this file since 109 was 109, checked in by pinsard, 18 years ago

modification of savesaxo.sh to fix ticket 17
File size: 34.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 2.0 -->
18
19<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
20  <head>
21    <title>IDLdoc Developer's Help (SAXO 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 (SAXO Documentation)";
640      }
641    </script>
642  </head>
643
644
645  <body onload="setTitle();">
646
647    <div id="navbar_title">
648  <h1>SAXO Documentation</h1>
649</div>
650
651
652<div id="main_navbar">
653
654  <table cellspacing="0">
655    <tr>
656     
657      <td><a href="overview.html?format=raw" title="Overview of library">Overview</a></td>
658     
659
660     
661      <td >Directory</td>
662     
663
664     
665      <td><a href="idldoc-categories.html?format=raw" title="Browse library by category">Categories</a></td>
666     
667
668     
669      <td><a href="idldoc-index.html?format=raw" title="Index of files, routines, and parameters">Index</a></td>
670     
671
672     
673      <td><a href="search-page.html?format=raw" title="Search library">Search</a></td>
674     
675
676      <td >File</td>
677
678     
679      <td >Source</td>
680     
681
682     
683      <td id="selected">Help</td>
684     
685
686      <td >Etc</td>
687
688      <td id="flexible">Developer&nbsp;documentation</td>
689    </tr>
690  </table>
691
692</div>
693
694<div id="secondary_navbar">
695
696&lt;&lt; prev file | next file &gt;&gt;&nbsp;&nbsp;&nbsp;&nbsp;<a href="idldoc-dev-help.html" target="_TOP">view single page</a> | <a href="index.html?format=raw" target="_TOP">view frames</a>&nbsp;&nbsp;&nbsp;&nbsp;summary: fields | routine&nbsp;&nbsp;&nbsp;&nbsp;details: routine
697
698</div>
699
700
701    <div id="container">
702
703      <h1>IDLdoc developer's guide</h1>
704
705      <p>This guide discusses how to mark up IDL pro code in order to
706      insert more information into IDLdoc's output.</p>
707
708      <p>Comments on the routine and file level are placed between
709      ";+" and ";-" lines before a routine in IDL source code. Content
710      between these lines is copied verbatim into the IDLdoc output
711      for the routine it appears before with the exception of the
712      @-preceded "tags" listed in tables below. Once an @ appears in
713      the comments, IDLdoc processes all remaining lines of the
714      comments as tags. To place a non-tag defining "@" in your
715      comments, escape it with a "\", as in
716      "email_address\@rsinc.com".</p>
717
718      <p>In the following example, the @author tag is used to indicate
719      an author of the code. The second "@" is escaped to allow its
720      literal use in the email address:</p>
721
722        <pre class="snippet">; @author Michael Galloy, mgalloy\@rsinc.com</pre>
723
724      <h2>Routine level comments</h2>
725
726      <p>There are many tags which describe an individual
727      routine. Each tag name appears after an "@" sign as the first
728      non-whitespace character after the ;. The tags are described
729      below.</p>
730
731      <table class="basic" cellspacing="0">
732        <tr>
733          <th>Tag</th>
734          <th>Description</th>
735        </tr>
736        <tr>
737          <td>abstract</td>
738          <td>
739            Presence of the this tag indicates this method is
740            abstract. This is intended for use with methods of a class
741            which are not intended to be called, but are only provided
742            as documenting an interface that a subclass will override.
743          </td>
744        </tr>
745        <tr>
746          <td>author</td>
747          <td>
748            Text following this tag appears in a list of attributes
749            of the routine marked as "Author."
750          </td>
751        </tr>
752        <tr>
753          <td>bugs</td>
754          <td>
755            Text that follows this tag is copied into a bug
756            attribute of the routine and placed in a library wide
757            listing which documents known failings of routines.
758          </td>
759        </tr>
760        <tr>
761          <td>categories</td>
762          <td>
763            Text following this tag is used as a comma separated list
764            of categories of the routine. The syntax is:
765
766            <pre class="snippet">; @categories math, input/output</pre>
767
768            Category names are case-sensitive and may contain any
769            characters except commas (though whitespace at the
770            beginning and end will be removed).
771          </td>
772        </tr>
773        <tr>
774          <td>copyright</td>
775          <td>
776            Text following this tag appears in a list of attributes
777            of the routine marked as "Copyright."
778          </td>
779        </tr>
780        <tr>
781          <td>customer_id</td>
782          <td>
783            Text following this tag appears in a list of attributes
784            of the routine marked as "Customer ID."
785          </td>
786        </tr>
787        <tr>
788          <td>examples</td>
789          <td>
790            Text following this tag is copied into an examples
791            attribute of the routine; it is intended to have
792            example code of using the routine.
793          </td>
794        </tr>
795        <tr>
796          <td>field</td>
797          <td>
798            For routines in files that end in "__define", this
799            provides documentation of a member variable of a
800            class/structure. The syntax is
801       
802            <pre class="snippet">; @field field_name comment</pre>
803       
804            where "field" matches one of the structure field names
805            of the structure type/class being defined.
806          </td>
807        </tr>
808        <tr>
809          <td>hidden</td>
810          <td>
811            Presence of this tag hides this routine in IDLdoc
812            output.
813          </td>
814        </tr>
815        <tr>
816          <td>history</td>
817          <td>
818            Text following this tag is copied into a history
819            attribute of the routine; it is intended to have a
820            history of the creators and modifiers of the source
821            code of the routine.
822          </td>
823        </tr>
824        <tr>
825          <td>inherits</td>
826          <td>
827            Obsolete. Intended to provide the parent class of the
828            documented class, but this is automatically handled by
829            IDLdoc now (as long as class definitions are in files
830            that end "__define").
831          </td>
832        </tr>
833        <tr>
834          <td>keyword</td>
835          <td>
836            This tag documents a single keyword parameter to the
837            routine. This syntax is
838       
839            <pre class="snippet">; @keyword keyword_name attributes comment</pre>
840       
841            Attributes further describe keyword and detailed in
842            the section below. The comment may be an text and is
843            copied into the IDLdoc output.
844          </td>
845        </tr>
846        <tr>
847          <td>obsolete</td>
848          <td>
849            Presence of this tag marks the routine as obsolete.
850          </td>
851        </tr>
852        <tr>
853          <td>param</td>
854          <td>
855            This tag documents a single keyword parameter to the
856            routine. This syntax is
857       
858            <pre class="snippet">; @param keyword_name attributes comment</pre>
859       
860            Attributes further describe keyword and detailed in
861            the section below. The comment may be an text and is
862            copied into the IDLdoc output.
863          </td>
864        </tr>
865        <tr>
866          <td>pre</td>
867          <td>
868            Text following this tag will be copied to a pre
869            attribute of the routine; it is intended to give
870            conditions the routine assumes to be true before it
871            runs.
872          </td>
873        </tr>
874        <tr>
875          <td>post</td>
876          <td>
877            Text following this tag will be copied to a post
878            attribute of the routine; it is intended to give
879            conditions the routine assumes to be true after it
880            runs.
881          </td>
882        </tr>
883        <tr>
884          <td>private</td>
885          <td>
886            Presence of this tag will hide this routine in IDLdoc
887            output if IDLdoc is run in "user" mode.
888          </td>
889        </tr>
890        <tr>
891          <td>requires</td>
892          <td>
893            Text following this tag is copied into the "Requires"
894            attribute of the routine; it is intended to provide
895            the version of IDL required to run the routine. For
896            example,
897       
898            <pre class="snippet">; @requires IDL 6.2</pre>
899       
900            will simply cause "IDL 6.2" to appear in the
901            "Requires" attribute.
902          </td>
903        </tr>
904        <tr>
905          <td>restrictions</td>
906          <td>
907            Text following this tag is copied into the
908            "Restrictions" attribute of the routine; it is
909            intended to provide any restrictions on the use of the
910            routine.
911          </td>
912        </tr>
913        <tr>
914          <td>returns</td>
915          <td>
916            Text following this tag is copied into the "Returns"
917            attribute of the routine; it is intended to provide
918            information about return value of a function.
919          </td>
920        </tr>
921        <tr>
922          <td>todo</td>
923          <td>
924            This tag places an item in a library-wide list of todo
925            items. The text following the tag is copied into this list
926            along with the routine it appears in it.
927          </td>
928        </tr>
929        <tr>
930          <td>uses</td>
931          <td>
932            Text following this tag is placed in a uses attribute of
933            the routine; it is intended to list routines that this
934            routine calls.
935          </td>
936        </tr>
937        <tr>
938          <td>version</td>
939          <td>
940            Text following this tag is placed in a version attribute
941            of the routine; it is intended to give a version
942            name/number of the routine.
943          </td>
944        </tr>
945      </table>
946
947      <p>For each positional parameters or keyword tag additional
948      attributes may be added in curly braces. For example,</p>
949       
950      <pre class="snippet">; @param x {in}{required}{type=lonarr} x-axis data</pre>
951       
952      <p>The attributes are described below.</p>
953
954      <table class="basic" cellspacing="0">
955        <tr>
956          <th>Attribute</th>
957          <th>Description</th>
958        </tr>
959        <tr>
960          <td>default</td>
961          <td>
962            This atrribute defines the default value of the
963            parameter. Any string may be entered and is echoed in the
964            IDLdoc output.
965          </td>
966        </tr>
967        <tr>
968          <td>hidden</td>
969          <td>
970            This attribute hides this parameter in IDLdoc output.
971          </td>
972        </tr>
973        <tr>
974          <td>in</td>
975          <td>
976            This attribute marks the parameter as an input to the
977            routine.
978          </td>
979        </tr>
980        <tr>
981          <td>optional</td>
982          <td>
983            This attribute marks the parameter as optional; the
984            routine does not always need this parameter, although
985            there might be cases where the parameter is required
986            (depending on the presence and value of other parameters).
987          </td>
988        </tr>
989        <tr>
990          <td>out</td>
991          <td>
992            This attribute marks the parameter as an output to the
993            routine. This routine expects a named variable to be
994            passed to this parameter (if passed at all).
995          </td>
996        </tr>
997        <tr>
998          <td>private</td>
999          <td>
1000            This attribute hides this parameter in IDLdoc output when
1001            IDLdoc is run in "user" mode and marking it as "private"
1002            when run in "developer" mode.
1003          </td>
1004        </tr>
1005        <tr>
1006          <td>required</td>
1007          <td>
1008            This attribute marks the parameter as required.
1009          </td>
1010        </tr>
1011        <tr>
1012          <td>type</td>
1013          <td>
1014            This atrribute defines the data type of the
1015            parameter. Any string may be entered and is echoed in
1016            the IDLdoc output. The special type "boolean" will cause
1017            the calling syntax in IDLdoc output to use the IDL
1018            online help syntax of prepending a "/" to the parameter
1019            name.
1020          </td>
1021        </tr>
1022      </table>
1023
1024      <h2>File level comments</h2>
1025
1026      <p>Some tags may appear in the comments for any routine in a
1027      file because they document attributes of the file. These tags
1028      are described below.</p>
1029
1030      <table class="basic" cellspacing="0">
1031        <tr>
1032          <th>Tag</th>
1033          <th>Description</th>
1034        </tr>
1035        <tr>
1036          <td>file_comments</td>
1037          <td>
1038            Text following the tag is copied to the top of the file
1039            in the IDLdoc output i.e. it is a comment on the file
1040            and not the routine it appears in. If there are multiple
1041            file_comments tags in the file, the comments will be
1042            concatenated in the order they are present in the file.
1043          </td>
1044        </tr>
1045        <tr>
1046          <td>hidden_file</td>
1047          <td>
1048            Presence of this tag indicates this entire file should
1049            be hidden in IDLdoc output.
1050          </td>
1051        </tr>
1052        <tr>
1053          <td>private_file</td>
1054          <td>
1055            Presence of this tag indicates this entire file should
1056            be hidden in IDLdoc output if IDLdoc is run in "user"
1057            mode, but shown when run in "developer" mode (the
1058            default).
1059          </td>
1060        </tr>
1061      </table>
1062
1063      <h2>Examples</h2>
1064
1065      For example, here's a sample class definition routine:
1066
1067      <pre class="snippet">;+
1068; Define the instance variables of the array_list.
1069;
1070; @file_comments An array_list is an object representing a variable
1071;                length list of scalar elements of any single type.
1072;                Array_lists support adding elements at the end of
1073;                the vector only, but any element may be removed from
1074;                the array_list. An iterator is provided for
1075;                efficient and easy looping throught the elements of
1076;                the array_list.
1077;
1078; @field data pointer to an array
1079; @field cur_size the current size of the data in the array
1080; @field max_size the maximum size of the data in the current array
1081; @field type type code (as in SIZE function) for the elements in the
1082;        array_list
1083; @field sample_struct pointer to a structure if the type is
1084;        "structure"
1085; @field iterators IDL_Container for the iterators of this array_list
1086;
1087; @requires IDL 6.0
1088;
1089; @author Michael D. Galloy
1090; @history Created September 26, 2003
1091; @copyright RSI, 2003
1092;-
1093pro array_list__define
1094    compile_opt idl2
1095
1096    define = { array_list, $
1097        data:ptr_new(), $
1098        cur_size:0L, $
1099        max_size:0L, $
1100        type:0L, $
1101        sample_struct:ptr_new(), $
1102        iterators:obj_new() $
1103        }
1104end</pre>       
1105
1106      Another example routine, this time a simple function with a positional parameter and keyword:
1107
1108      <pre class="snippet">;+
1109; Returns [b, a] for a linear function y = a * x + b that sends
1110; inRange[0] -> range[0] and inRange[1] -> range[1].
1111;
1112; @returns dblarr(2)
1113; @param inRange {in}{required}{type=2 element numeric array} input
1114;        range
1115; @keyword range {in}{optional}{type=dblarr(2)}{default=[0.D, 1.D]}
1116;          output range
1117; @categories math, object graphics
1118;-
1119function linear_function, inRange, range=outRange
1120    compile_opt idl2
1121
1122    i_outRange = n_elements(outRange) eq 0 $
1123        ? [0.D, 1.D] $
1124        : double(outRange)
1125
1126    scale = [i_outRange[0] * inRange[1] - i_outRange[1] * inRange[0], $
1127        i_outRange[1] - i_outRange[0]] / (inRange[1] - inRange[0])
1128    return, scale
1129end</pre>
1130
1131      One more example, this time a function method with an output keyword.
1132
1133      <pre class="snippet">;+
1134; Finds the value associated with the given key.
1135;
1136; @returns the value of the associated key or -1L if not found
1137; @param key {in}{type=key type} key to look up
1138; @keyword found {out}{optional}{type=boolean} true if value found for
1139;          given key
1140;-
1141function hash_table::get, key, found=found</pre>
1142
1143      <h2>Directory overviews</h2>
1144
1145      <p>The "dir-overview" file in each directory of the library is
1146      copied into the directory overview file. Much of the content of
1147      the overview file is obtained from the PRO code files in the
1148      directory, but this allows header content as an overview of the
1149      all the files in the directory to be inserted at the top of the
1150      directory overview file.</p>
1151
1152
1153      <h2>Library overview</h2>
1154
1155      <p>The library overview file is a single file which is inserted
1156      into the opening page of the IDLdoc output. This file is copied
1157      verbatim into the IDLdoc output except for the following tag
1158      which allows for comments on the contents of the directories
1159      found in the library.</p>
1160
1161      <table class="basic" cellspacing="0">
1162        <tr>
1163          <th>Tag</th>
1164          <th>Description</th>
1165        </tr>
1166        <tr>
1167          <td>dir</td>
1168          <td>
1169            The text following this tag is the relative path
1170            (web-style, always with a /) to a directory in the
1171            library and a comment which is copied into a table in
1172            the opening page of the IDLdoc output.
1173       
1174            <pre class="snippet">; @dir algorithms/math mathematical routines</pre>
1175          </td>
1176        </tr>
1177      </table>
1178
1179      <h2>Syntax of IDLdoc routine</h2>
1180
1181      <p>Below is the IDLdoc generated documentation for the IDLdoc main routine.</p>
1182
1183        <div class="routine_details" id="_idldoc">
1184
1185          <h2><a class="top" href="#container">top</a>idldoc</h2>
1186       
1187          <p class="header">
1188            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>
1189       
1190          <div class="comments">Calling routine for IDLdoc.</div>
1191
1192            <h3>Keywords</h3>
1193           
1194            <h4 id="_idldoc_keyword_root">root&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1195              <span class="attr">in</span>
1196              <span class="attr">required</span>
1197              <span class="attr">type:</span> <span class="value">string</span>
1198            </h4>
1199       
1200            <div class="comments"> root directory for IDLdoc's
1201            recursive search for .pro files.  IDLdoc will find any
1202            files with the '.pro' suffix and include them in its file
1203            listings.  Only directories with '.pro' files in them are
1204            included in the directory listings.</div>
1205           
1206            <h4 id="_idldoc_keyword_output">output&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1207              <span class="attr">in</span>
1208              <span class="attr">optional</span>
1209              <span class="attr">type:</span> <span class="value">string</span>
1210              <span class="attr">default:</span> <span class="value">same as root</span>
1211            </h4>
1212       
1213            <div class="comments">
1214            directory in which to create the HTML output and possible
1215            subdirectories</div>
1216           
1217            <h4 id="_idldoc_keyword_overview">overview&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1218              <span class="attr">in</span>
1219              <span class="attr">optional</span>
1220              <span class="attr">type:</span> <span class="value">string</span>
1221            </h4>
1222       
1223            <div class="comments"> filepath to a file containing the
1224            summary of the package information about each directory in
1225            the package.</div>
1226           
1227            <h4 id="_idldoc_keyword_footer">footer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1228              <span class="attr">in</span>
1229              <span class="attr">optional</span>
1230              <span class="attr">type:</span> <span class="value">string</span>
1231            </h4>
1232       
1233            <div class="comments"> filename for a footer to be placed
1234            at the bottom of files; this file can contain any valid
1235            HTML</div>
1236           
1237            <h4 id="_idldoc_keyword_log_file">log_file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1238              <span class="attr">in</span>
1239              <span class="attr">optional</span>
1240              <span class="attr">type:</span> <span class="value">string</span>
1241            </h4>
1242       
1243            <div class="comments"> set to a filename of a file to
1244            contain the error messages generated by the IDLdoc run;
1245            useful for automated runs of IDLdoc</div>
1246           
1247            <h4 id="_idldoc_keyword_user">user&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1248              <span class="attr">in</span>
1249              <span class="attr">optional</span>
1250              <span class="attr">type:</span> <span class="value">boolean</span>
1251            </h4>
1252       
1253            <div class="comments"> set to create a listing appropriate
1254            for <em>users</em> of the given library hierarchy; the
1255            default is to create documentation suited to developers.
1256            If set private routines are not shown in the
1257            documentation.</div>
1258           
1259            <h4 id="_idldoc_keyword_quiet">quiet&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1260              <span class="attr">in</span>
1261              <span class="attr">optional</span>
1262              <span class="attr">type:</span> <span class="value">boolean</span>
1263            </h4>
1264       
1265            <div class="comments"> if set, print only
1266            warnings</div>
1267           
1268            <h4 id="_idldoc_keyword_silent">silent&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1269              <span class="attr">in</span>
1270              <span class="attr">optional</span>
1271              <span class="attr">type:</span> <span class="value">boolean</span>
1272            </h4>
1273       
1274            <div class="comments"> if set, print no
1275            messages</div>
1276           
1277            <h4 id="_idldoc_keyword_embed">embed&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1278              <span class="attr">in</span>
1279              <span class="attr">optional</span>
1280              <span class="attr">type:</span> <span class="value">boolean</span>
1281            </h4>
1282       
1283            <div class="comments"> if set, embeds style sheet in each
1284            HTML document; if this is not set, each HTML file will be
1285            looking for the cascading style sheet idldoc.css in the
1286            directory specified for the ROOT keyword</div>
1287           
1288            <h4 id="_idldoc_keyword_nonavbar">nonavbar&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 exclude the
1295            navigation bar at the top of each page</div>
1296           
1297            <h4 id="_idldoc_keyword_title">title&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">string</span>
1301              <span class="attr">default:</span> <span class="value">Research Systems</span>
1302            </h4>
1303       
1304            <div class="comments"> title of
1305            the library</div>
1306           
1307            <h4 id="_idldoc_keyword_subtitle">subtitle&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1308              <span class="attr">in</span>
1309              <span class="attr">optional</span>
1310              <span class="attr">type:</span> <span class="value">string</span>
1311              <span class="attr">default:</span> <span class="value">IDL version</span>
1312            </h4>
1313       
1314            <div class="comments"> subtitle of
1315            the library</div>
1316           
1317            <h4 id="_idldoc_keyword_statistics">statistics&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1318              <span class="attr">in</span>
1319              <span class="attr">optional</span>
1320              <span class="attr">type:</span> <span class="value">boolean</span>
1321            </h4>
1322       
1323            <div class="comments"> set to calculate several
1324            McCabe statistics for each routine</div>
1325           
1326            <h4 id="_idldoc_keyword_n_warnings">n_warnings&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1327              <span class="attr">out</span>
1328              <span class="attr">optional</span>
1329              <span class="attr">type:</span> <span class="value">integer</span>
1330            </h4>
1331       
1332            <div class="comments"> set to a named variable to
1333            contain the total number of warnings issued during the run</div>
1334           
1335            <h4 id="_idldoc_keyword_browse_routines">browse_routines&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1336              <span class="attr">in</span>
1337              <span class="attr">optional</span>
1338              <span class="attr">type:</span> <span class="value">boolean</span>
1339            </h4>
1340       
1341            <div class="comments"> set to include a frame
1342            to browse through the routines of the current file</div>
1343           
1344            <h4 id="_idldoc_keyword_preformat">preformat&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1345              <span class="attr">in</span>
1346              <span class="attr">optional</span>
1347              <span class="attr">type:</span> <span class="value">boolean</span>
1348            </h4>
1349       
1350            <div class="comments"> set to produce output that
1351            will look like it does in the code files (line for line)</div>
1352           
1353            <h4 id="_idldoc_keyword_assistant">assistant&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1354              <span class="attr">in</span>
1355              <span class="attr">optional</span>
1356              <span class="attr">type:</span> <span class="value">boolean</span>
1357            </h4>
1358       
1359            <div class="comments"> set to produce output for the
1360            IDL assistant help system instead of optimized for a web browser
1361            </div>
1362                 
1363          <h3>Examples</h3><div class="value"> To run IDLdoc, try:
1364            <center><code>idldoc, root='C:\mycode'</code></center>
1365            where C:\mycode is the root of a directory tree containing IDL
1366            .pro files.
1367            </div>
1368
1369          <h3>Version history</h3>
1370
1371          <h4>Author</h4><div class="value"> Michael D. Galloy</div>
1372         
1373          <h4>Copyright</h4><div class="value"> RSI, 2002</div>
1374         
1375          <h3>Other attributes</h3>
1376         
1377          <h4>Requires IDL version</h4><div class="value"> IDL 6.0</div>
1378       
1379        </div>
1380       
1381
1382
1383     
1384
1385      <div id="tagline">Produced by IDLdoc 2.0.</div>
1386
1387    </div>
1388
1389  </body>
1390</html>
Note: See TracBrowser for help on using the repository browser.