Changeset 689 for trunk

Show
Ignore:
Timestamp:
09/05/10 21:07:02 (21 months ago)
Author:
mgalloy
Message:

Adding to reference guide and tutorial.

Location:
trunk/reference
Files:
2 modified

Legend:

Unmodified
Added
Removed

  • trunk/reference/idldoc-reference.rst

    r674 r689  
    1 IDLdoc Reference 
    2 ================ 
     1IDLdoc 3.3 Reference 
     2==================== 
    33 
    44:Author: Michael Galloy 
    5 :Date: 24 August 2010 
    6  
    7  
    8 IDLdoc keywords 
    9 ~~~~~~~~~~~~~~~ 
     5 
     6 
     7IDLdoc installation 
     8------------------- 
     9 
     10To install IDLdoc, simply unzip and place the IDLdoc distribution in your IDL path. Do not separate the contents of the distribution; the code looks for files in locations relative to itself. 
     11 
     12 
     13IDLdoc routine keywords 
     14----------------------- 
     15 
     16There are quite a few keywords to IDLdoc to set various specifications for the output. Also see the "Customizing Output" section for using templates for customized output. 
     17 
     18=================== ======================================================== 
     19Keyword             Description 
     20=================== ======================================================== 
     21`ASSISTANT`         obsolete; no longer used 
     22`BROWSE_ROUTINES`   obsolete; no longer used 
     23`CHARSET`           set to the character set to be used for the output,  
     24                    default is "utf-8" 
     25`COMMENT_STYLE`     output format for comments ("html", "rst", or "latex");  
     26                    default is "html" 
     27`DEBUG`             set to allow crashes with a stack trace instead of the  
     28                    default simple message 
     29`EMBED`             embed CSS stylesheet instead of linking to it (useful for  
     30                    documentation where individual pages must stand by  
     31                    themselves) 
     32`ERROR`             set to a named variable to return the error state of the  
     33                    IDLdoc call; 0 indicates no error, anything else is an  
     34                    error 
     35`FOOTER`            filename of file to insert into the bottom of each page of  
     36                    docs 
     37`FORMAT_STYLE`      style to use to parse file and routine comments ("idl", 
     38                    "idldoc", "verbatim", or "rst"); default is "idldoc" 
     39`HELP`              set to print out the syntax of an IDLdoc call 
     40`LOG_FILE`          if present, send messages to this filename instead of  
     41                    *stdout* 
     42`MARKUP_STYLE`      markup used in comments ("rst" or "verbatim"); default is 
     43                    "verbatim" 
     44`N_WARNINGS`        set to a named variable to return the number of warnings  
     45                    for the IDLdoc run 
     46`NONAVBAR`          set to not display the navbar 
     47`NOSOURCE`          set to not put source code into output 
     48`OUTPUT`            directory to place output; if not present, output will be  
     49                    placed in the `ROOT` directory            
     50`OVERVIEW`          filename of overview text and directory information 
     51`PREFORMAT`         obsolete; no longer used 
     52`QUIET`             if set, don't print info messages, only print warnings and  
     53                    errors 
     54`ROOT`              root of directory hierarchy to document; this is the only  
     55                    required keyword 
     56`SILENT`            if set, don't print any messages 
     57`STATISTICS`        set to generate complexity statistics for routines 
     58`SUBTITLE`          subtitle for docs 
     59`TEMPLATE_PREFIX`   prefix for template's names 
     60`TEMPLATE_LOCATION` set to directory to find templates in 
     61`TITLE`             title of docs 
     62`USER`              set to generate user-level docs (private parameters, files  
     63                    are not shown); the default is developer-level docs  
     64                    showing files and parameters 
     65`VERSION`           set to print out the version of IDLdoc 
     66=================== ======================================================== 
     67 
    1068 
    1169 
    1270Format styles 
    13 ~~~~~~~~~~~~~ 
     71------------- 
    1472 
    1573 
    1674rst format style 
    17 ---------------- 
     75~~~~~~~~~~~~~~~~ 
     76 
     77The following tags are available in file comments (i.e. comment headers not immediately preceeding/following a routine header). 
     78 
     79============== ============ ============ ==================================== 
     80Tag name       Arguments    Attributes   Description 
     81============== ============ ============ ==================================== 
     82`:Author:`     comments     none         specifies the author of the file 
     83`:Copyright:`  comments     none         specifies the copyright information  
     84                                         for the file 
     85`:Examples:`   comments     none         specifies examples of usage 
     86`:Hidden:`     none         none         if present, indicates the file is not   
     87                                         to be shown in the documentation 
     88`:History:`    comments     none         lists the history for the file 
     89`:Private:`    none         none         if present, indicates the file should  
     90                                         not shown in user-level documentation  
     91                                         (set with the `USER` keyword to  
     92                                         IDLdoc) 
     93`:Properties:` property     none         describes properties of a class,                                           
     94               name,                     i.e., a keyword to `getProperty`,  
     95               comments                  `setProperty`, or `init` 
     96`:Version:`    comments     none         specifies the version of the file 
     97============== ============ ============ ==================================== 
     98 
     99 
     100The following tags are available for comments immediately before or after a routine header. 
     101 
     102================= ============ ========== ================================= 
     103Tag name          Arguments    Attributes Description 
     104================= ============ ========== ================================= 
     105`:Abstract:`      none         none       if present, indicates the method is  
     106                                          not implemented and present only to  
     107                                          specify the interface to subclasses'  
     108                                          implementations 
     109`:Author:`        comments     none       specifies the author of the routine 
     110`:Bugs:`          comments     none       specifies any issues found in the  
     111                                          routine 
     112`:Categories:`    list         none       specifies a comma-separated list of  
     113                                          category names 
     114`:Copyright:`     comments     none       specifies the copyright for the  
     115                                          routine 
     116`:Customer_id:`   comments     none       specifies a customer ID for the  
     117                                          routine 
     118`:Description:`   comments     none       a tag for the standard comments for  
     119                                          a routine; will be appended to  
     120                                          standard comments if both are  
     121                                          present 
     122`:Examples:`      comments     none       specifies examples of using the  
     123                                          routine 
     124`:Fields:`        fieldname    none       specifies the names of the field  
     125                  and comments            followed by a description of the  
     126                                          field 
     127`:File_comments:` comments     none       equivalent to the main section in  
     128                                          file-level comments 
     129`:Hidden:`        none         none       if present, indicate the routine  
     130                                          should not be shown in the  
     131                                          documentation 
     132`:Hidden_file:`   none         none       if present, indicates the file  
     133                                          containing this routine should not  
     134                                          be shown in the documentation 
     135`:History:`       comments     none       specifies the history of the  
     136                                          routine 
     137`:Inherits:`      none         none       not used 
     138`:Keywords:`      keyword name see below        documents keywords of the routine 
     139`:Obsolete:`      none         none       if present, indicates the routine is  
     140                                          obsolete 
     141`:Params:`        param name   see below  documents positional parameters of  
     142                                          the routine 
     143`:Post:`          comments     none       specifies any post-conditions of the  
     144                                          routine 
     145`:Pre:`           comments     none       specifies any pre-conditions of the  
     146                                          routine 
     147`:Private:`       none         none       if present, indicates the routine  
     148                                          should not shown in user-level  
     149                                          documentation (set with the `USER`  
     150                                          keyword to IDLdoc) 
     151`:Private_file:`  comments     none       if present, indicates the file  
     152                                          containing this routine should not  
     153                                          shown in user-level documentation  
     154                                          (set with the `USER` keyword to  
     155                                          IDLdoc) 
     156`:Requires:`      comments     none       specifies the IDL version of the  
     157                                          routine; IDLdoc finds the routines  
     158                                          requiring the highest IDL version  
     159                                          and reports them on the warnings  
     160                                          page 
     161`:Returns:`       comments     none       specifies the return value of the  
     162                                          function 
     163`:Todo:`          comments     none       specifies any todo items left for  
     164                                          the routine 
     165`:Uses:`          comments     none       specifies any other routines,  
     166                                          classes, etc. needed by the routine 
     167`:Version:`       comments     none       specifies the version of the  
     168                                          routine 
     169================= ============ ========== ================================= 
     170 
     171 
     172 
     173overview files tags 
     174 
     175directory overview file tags 
    18176 
    19177 
    20178IDLdoc format style 
    21 ------------------- 
     179~~~~~~~~~~~~~~~~~~~ 
     180 
     181The following tags are available in file comments (i.e. comment headers not immediately preceeding/following a routine header). 
     182 
     183=============== ============ ============ =================================== 
     184Tag name        Arguments    Attributes   Description 
     185=============== ============ ============ =================================== 
     186`@author`       comments     none         specifies the author of the file 
     187`@copyright`    comments     none         specifies the copyright information  
     188                                          for the file 
     189`@examples`     comments     none         specifies examples of usage 
     190`@hidden`       none         none         if present, indicates the file is  
     191                                          not to be shown in the documentation 
     192`@history`      comments     none         lists the history for the file 
     193`@private`      none         none         if present, indicates the file  
     194                                          should not shown in user-level  
     195                                          documentation (set with the `USER`  
     196                                          keyword to IDLdoc) 
     197`@property`     property     none         describes a property of a class,  
     198                name,                     i.e., a keyword to `getProperty`, 
     199                comments                  `setProperty`, or `init` 
     200`@version`      comments     none         specifies the version of the file 
     201=============== ============ ============ =================================== 
     202 
     203The following tags are available for comments immediately before or after a routine header. 
     204 
     205================ ============ =========== =================================== 
     206Tag name         Arguments    Attributes  Description 
     207================ ============ =========== =================================== 
     208`@abstract`      none         none        if present, indicates the method is  
     209                                          not implemented and present only to  
     210                                          specify the interface to subclasses'  
     211                                          implementations 
     212`@author`        comments     none        specifies the author of the routine 
     213`@bugs`          comments     none        specifies any issues found in the  
     214                                          routine 
     215`@categories`    list         none        specifies a comma-separated list of  
     216                                          category names 
     217`@copyright`     comments     none        specifies the copyright for the  
     218                                          routine 
     219`@customer_id`   comments     none        specifies a customer ID for the  
     220                                          routine 
     221`@description`   comments     none        a tag for the standard comments for  
     222                                          a routine; will be appended to  
     223                                          standard comments if both are  
     224                                          present 
     225`@examples`      comments     none        specifies examples of using the  
     226                                          routine 
     227`@field`         fieldname    none        specifies the name of the field  
     228                 and comments             followed by a description of the  
     229                                          field 
     230`@file_comments` comments     none        equivalent to the main section in  
     231                                          file-level comments 
     232`@hidden`        none         none        if present, indicate the routine  
     233                                          should not be shown in the  
     234                                          documentation 
     235`@hidden_file`   none         none        if present, indicates the file  
     236                                          containing this routine should not  
     237                                          be shown in the documentation 
     238`@history`       comments     none        specifies the history of the  
     239                                          routine 
     240`@inherits`      none         none        not used 
     241`@keyword`       keyword name see below   documents a keyword of the routine 
     242`@obsolete`      none         none        if present, indicates the routine is  
     243                                          obsolete 
     244`@param`         param name   see below   documents a positional parameter of  
     245                                          the routine 
     246`@post`          comments     none        specifies any post-conditions of the  
     247                                          routine 
     248`@pre`           comments     none        specifies any pre-conditions of the  
     249                                          routine 
     250`@private`       none         none        if present, indicates the routine  
     251                                          should not shown in user-level  
     252                                          documentation (set with the `USER`  
     253                                          keyword to IDLdoc) 
     254`@private_file`  comments     none        if present, indicates the file  
     255                                          containing this routine should not  
     256                                          shown in user-level documentation  
     257                                          (set with the `USER` keyword to  
     258                                          IDLdoc) 
     259`@requires`      comments     none        specifies the IDL version of the  
     260                                          routine; IDLdoc finds the routines  
     261                                          requiring the highest IDL version  
     262                                          and reports them on the warnings  
     263                                          page 
     264`@returns`       comments     none        specifies the return value of the  
     265                                          function 
     266`@todo`          comments     none        specifies any todo items left for  
     267                                          the routine 
     268`@uses`          comments     none        specifies any other routines,  
     269                                          classes, etc. needed by the routine 
     270`@Version`       comments     none        specifies the version of the  
     271                                          routine 
     272================ ============ =========== =================================== 
     273 
     274 
     275overview files tags 
     276 
     277directory overview file tags 
    22278 
    23279 
    24280IDL format style 
    25 ---------------- 
     281~~~~~~~~~~~~~~~~ 
     282 
     283file tags 
     284 
     285routine tags 
     286 
     287overview files tags 
     288 
     289directory overview file tags 
    26290 
    27291 
    28292Markup styles 
    29 ~~~~~~~~~~~~~ 
     293------------- 
    30294 
    31295 
    32296rst markup style 
    33 ---------------- 
     297~~~~~~~~~~~~~~~~ 
    34298 
    35299 
    36300plain markup style 
     301~~~~~~~~~~~~~~~~~~ 
     302 
     303 
     304Customizing output 
    37305------------------ 
     306 

  • trunk/reference/idldoc-tutorial.rst

    r688 r689  
    4949 
    5050This places the IDLdoc version information into the title/subtitle of the documentation. We'll talk about some of the other options in the following sections. 
     51 
     52Note: By default, IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your `!PATH` can cause IDL to choose the (possibly outdated) copy in the docs over the correct source file. It is recommended to either place your docs outside your `!PATH` or use the `NOSOURCE` keyword. 
    5153 
    5254