Context Navigation

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

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

Note: See TracBrowser for help on using the repository browser.

Download in other formats: