Changeset 693 for trunk

Show
Ignore:
Timestamp:
09/07/10 16:13:35 (21 months ago)
Author:
mgalloy
Message:

Nearly done with draft of the reference guide.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/reference/idldoc-reference.rst

    r692 r693  
    9696  `:History:`    comments     none         lists the history for the file 
    9797  `:Private:`    none         none         if present, indicates the file  
    98                                            should not shown in user-level  
     98                                           should not be shown in user-level  
    9999                                           documentation  
    100100                                           (set with the `USER` keyword to  
    … …  
    135135  `:Examples:`      comments     none       specifies examples of using the  
    136136                                            routine 
    137   `:Fields:`        fieldname    none       specifies the names of the field  
    138                     and comments            followed by a description of the  
     137  `:Fields:`        fields       none       specifies the names of the field  
     138                                            followed by a description of the  
    139139                                            field 
    140140  `:File_comments:` comments     none       equivalent to the main section in  
    … …  
    149149                                            routine 
    150150  `:Inherits:`      none         none       not used 
    151   `:Keywords:`      keyword name see below      documents keywords of the routine 
     151  `:Keywords:`      params       see below  documents keywords of the routine 
    152152  `:Obsolete:`      none         none       if present, indicates the routine  
    153153                                            is obsolete 
    154   `:Params:`        param name   see below  documents positional parameters of  
     154  `:Params:`        params       see below  documents positional parameters of  
    155155                                            the routine 
    156156  `:Post:`          comments     none       specifies any post-conditions of  
    … …  
    159159                                            the routine 
    160160  `:Private:`       none         none       if present, indicates the routine  
    161                                             should not shown in user-level  
     161                                            should not be shown in user-level  
    162162                                            documentation (set with the `USER`  
    163163                                            keyword to IDLdoc) 
    … …  
    203203 
    204204 
    205 TODO: overview files tags 
    206  
    207 TODO: directory overview file tags 
     205The tags available in an overview file describe the entire library. There are a few tags shared with the file tags and the additional `:Dirs:` tag which provides a simple table of contents for the directories in the library. 
     206 
     207.. table:: rst format style tags for overview files 
     208 
     209  ================= ============ ========== ================================= 
     210  Tag name          Arguments    Attributes Description 
     211  ================= ============ ========== ================================= 
     212  `:Author:`        comments     none       specifies the author of the  
     213                                            library 
     214  `:Copyright:`     comments     none       specifies the copyright for the  
     215                                            library 
     216  `:Dirs:`          dirs         none       lists directories in the library 
     217                                            along with a description for each 
     218  `:History:`       comments     none       specifies the history of the  
     219                                            library 
     220  `:Version:`       comments     none       specifies the version of the  
     221                                            library 
     222  ================= ============ ========== ================================= 
     223 
     224Directory overview files also have a few tags shared with file tags. 
     225 
     226.. table:: rst format style tags for overview files 
     227 
     228  ================= ============ ========== ================================= 
     229  Tag name          Arguments    Attributes Description 
     230  ================= ============ ========== ================================= 
     231  `:Author:`        comments     none       specifies the author of the  
     232                                            files in the directory 
     233  `:Copyright:`     comments     none       specifies the copyright for the  
     234                                            files in the directory 
     235  `:Hidden:`        none         none       if present, indicate the routine  
     236                                            should not be shown in the  
     237                                            documentation                                             
     238  `:History:`       comments     none       specifies the history of the  
     239                                            library 
     240  `:Private:`       none         none       if present, indicates the  
     241                                            directory should not be shown in  
     242                                            user-level documentation (set with  
     243                                            the `USER` keyword to IDLdoc) 
     244  ================= ============ ========== ================================= 
    208245 
    209246 
    … …  
    227264  `@history`      comments     none         lists the history for the file 
    228265  `@private`      none         none         if present, indicates the file  
    229                                             should not shown in user-level  
     266                                            should not be shown in user-level  
    230267                                            documentation (set with the `USER`  
    231268                                            keyword to IDLdoc) 
    … …  
    288325                                            the routine 
    289326  `@private`       none         none        if present, indicates the routine  
    290                                             should not shown in user-level  
     327                                            should not be shown in user-level  
    291328                                            documentation (set with the `USER`  
    292329                                            keyword to IDLdoc) 
    … …  
    331368  =============== ================= ========================================== 
    332369 
    333 TODO: overview files tags 
    334  
    335 TODO: directory overview file tags 
     370The tags available in an overview file describe the entire library. There are a few tags shared with the file tags and the additional `@dir` tag which provides a simple table of contents for the directories in the library. 
     371 
     372.. table:: rst format style tags for overview files 
     373 
     374  ================= ============ ========== ================================= 
     375  Tag name          Arguments    Attributes Description 
     376  ================= ============ ========== ================================= 
     377  `@author`         comments     none       specifies the author of the  
     378                                            library 
     379  `@copyright`      comments     none       specifies the copyright for the  
     380                                            library 
     381  `@dir`            dir          none       lists directory in the library 
     382                                            along with a description for each 
     383  `@history`        comments     none       specifies the history of the  
     384                                            library 
     385  `@version`        comments     none       specifies the version of the  
     386                                            library 
     387  ================= ============ ========== ================================= 
     388 
     389Directory overview files also have a few tags shared with file tags. 
     390 
     391.. table:: rst format style tags for overview files 
     392 
     393  ================= ============ ========== ================================= 
     394  Tag name          Arguments    Attributes Description 
     395  ================= ============ ========== ================================= 
     396  `@author`         comments     none       specifies the author of the  
     397                                            files in the directory 
     398  `@copyright`      comments     none       specifies the copyright for the  
     399                                            files in the directory 
     400  `@hidden`         none         none       if present, indicate the routine  
     401                                            should not be shown in the  
     402                                            documentation                                             
     403  `@history`        comments     none       specifies the history of the  
     404                                            library 
     405  `@private`        none         none       if present, indicates the  
     406                                            directory should not be shown in  
     407                                            user-level documentation (set with  
     408                                            the `USER` keyword to IDLdoc) 
     409  ================= ============ ========== ================================= 
    336410 
    337411 
    … …  
    339413~~~~~~~~~~~~~~~~ 
    340414 
    341 TODO: file tags 
    342  
    343 TODO: routine tags 
    344  
    345 TODO: overview files tags 
    346  
    347 TODO: directory overview file tags 
     415The IDL format style attempts to extract information from code using the IDL template, i.e., the form shown in `template.pro` in the `examples` directory of the IDL distribution. :: 
     416 
     417  ;+ 
     418  ; NAME: 
     419  ;     ROUTINE_NAME 
     420  ; 
     421  ; PURPOSE: 
     422  ;     Tell what your routine does here.  I like to start with the words: 
     423  ;     "This function (or procedure) ..." 
     424  ;     Try to use the active, present tense. 
     425  ; 
     426  ; CATEGORY: 
     427  ;     Put a category (or categories) here.  For example: 
     428  ;     Widgets. 
     429  ; 
     430  ; CALLING SEQUENCE: 
     431  ;     Write the calling sequence here. Include only positional parameters 
     432  ;     (i.e., NO KEYWORDS). For procedures, use the form: 
     433  ; 
     434  ;     ROUTINE_NAME, Parameter1, Parameter2, Foobar 
     435  ; 
     436  ;     Note that the routine name is ALL CAPS and arguments have Initial 
     437  ;     Caps.  For functions, use the form: 
     438  ;  
     439  ;     Result = FUNCTION_NAME(Parameter1, Parameter2, Foobar) 
     440  ; 
     441  ;     Always use the "Result = " part to begin. This makes it super-obvious 
     442  ;     to the user that this routine is a function! 
     443  ; 
     444  ; INPUTS: 
     445  ;     Parm1:  Describe the positional input parameters here. Note again 
     446  ;             that positional parameters are shown with Initial Caps. 
     447  ; 
     448  ; OPTIONAL INPUTS: 
     449  ;     Parm2:  Describe optional inputs here. If you don't have any, just 
     450  ;             delete this section. 
     451  ;      
     452  ; KEYWORD PARAMETERS: 
     453  ;     KEY1:   Document keyword parameters like this. Note that the keyword 
     454  ;             is shown in ALL CAPS! 
     455  ; 
     456  ;     KEY2:   Yet another keyword. Try to use the active, present tense 
     457  ;             when describing your keywords.  For example, if this keyword 
     458  ;             is just a set or unset flag, say something like: 
     459  ;             "Set this keyword to use foobar subfloatation. The default 
     460  ;              is foobar superfloatation." 
     461  ; 
     462  ; OUTPUTS: 
     463  ;     Describe any outputs here.  For example, "This function returns the 
     464  ;     foobar superflimpt version of the input array."  This is where you 
     465  ;     should also document the return value for functions. 
     466  ; 
     467  ; OPTIONAL OUTPUTS: 
     468  ;     Describe optional outputs here.  If the routine doesn't have any,  
     469  ;     just delete this section. 
     470  ; 
     471  ; COMMON BLOCKS: 
     472  ;     BLOCK1: Describe any common blocks here. If there are no COMMON 
     473  ;             blocks, just delete this entry. 
     474  ; 
     475  ; SIDE EFFECTS: 
     476  ;     Describe "side effects" here.  There aren't any?  Well, just delete 
     477  ;     this entry. 
     478  ; 
     479  ; RESTRICTIONS: 
     480  ;     Describe any "restrictions" here.  Delete this section if there are 
     481  ;     no important restrictions. 
     482  ; 
     483  ; PROCEDURE: 
     484  ;     You can describe the foobar superfloatation method being used here. 
     485  ;     You might not need this section for your routine. 
     486  ; 
     487  ; EXAMPLE: 
     488  ;     Please provide a simple example here. An example from the 
     489  ;     DIALOG_PICKFILE documentation is shown below. Please try to 
     490  ;     include examples that do not rely on variables or data files 
     491  ;     that are not defined in the example code. Your example should 
     492  ;     execute properly if typed in at the IDL command line with no 
     493  ;     other preparation.  
     494  ; 
     495  ;       Create a DIALOG_PICKFILE dialog that lets users select only 
     496  ;       files with the extension `pro'. Use the `Select File to Read' 
     497  ;       title and store the name of the selected file in the variable 
     498  ;       file. Enter: 
     499  ; 
     500  ;       file = DIALOG_PICKFILE(/READ, FILTER = '*.pro')  
     501  ; 
     502  ; MODIFICATION HISTORY: 
     503  ;     Written by:     Your name here, Date. 
     504  ;     July, 1994      Any additional mods get described here.  Remember to 
     505  ;                     change the stuff above if you add a new keyword or 
     506  ;                     something! 
     507  ;- 
     508   
     509The routine and file headings are shown in the table below. 
     510 
     511.. table:: IDL format style routine and file headings 
     512 
     513  ======================== ================================================== 
     514  Heading name             Description 
     515  ======================== ================================================== 
     516  `calling sequence`       calling sequence for the routine; unneeded since 
     517                           IDLdoc gets the calling sequence from the routine 
     518                           declaration 
     519  `category`               TODO: 
     520  `common blocks`          TODO: 
     521  `example`                TODO: 
     522  `inputs`                 TODO: 
     523  `keyword parameters`     TODO: 
     524  `modification history`   TODO: 
     525  `name`                   name of the routine; unneeded since IDLdoc gets 
     526                           the name of the routine from the routine 
     527                           declaration 
     528  `optional inputs`        TODO: 
     529  `optional outputs`       TODO: 
     530  `outputs`                TODO: 
     531  `procedure`              TODO: 
     532  `purpose`                TODO: 
     533  `restrictions`           TODO: 
     534  `side effects`           TODO: 
     535  ======================== ================================================== 
     536 
     537There are no special headers for overview files or directory overview files using the IDL format style. 
    348538 
    349539 
    … …  
    351541------------- 
    352542 
    353 TODO: what are markup styles? 
     543Markup styles specify annotations of text comments. The valid markup styles are: "rst", "verbatim", and "preformattted". 
    354544 
    355545 
    … …  
    359549The *rst* markup style is the default markup style for the *rst* format style. 
    360550 
     551 
    361552verbatim markup style 
    362553~~~~~~~~~~~~~~~~~~~~~ 
    … …  
    374565------------------ 
    375566 
    376 TODO: write this section 
     567The output produced by IDLdoc can be customized by modifying the template files provides in the `templates/` directory of the IDLdoc distribution. 
     568 
     569TODO: template description 
     570 
     571TODO: new output type 
     572