document -- create a documentation node

Synopsis

• Usage:

  document { Key => key, ... }

• Inputs:
  • a list, with Hypertext, String, and special documentation entries as optional arguments such as Key => "..." (required)
• Optional inputs:
  • Key => a list, default value null, key of a documentation node
  • Headline => a list, default value null, headline of a documentation node
  • BaseFunction => a list, default value null, the basename of a function in a documentation node
  • Usage => a list, default value null, ways to use a function in a documentation node
  • Inputs => a list, default value null, inputs for a function in a documentation node
  • Outputs => a list, default value null, outputs for a function in a documentation node
  • Consequences => a list, default value null, side-effects of a function in a documentation node
  • Acknowledgement => a list, default value null, acknowledgements listed in a documentation node
  • Contributors => a list, default value null, non-author contributors listed in a documentation node
  • References => a list, default value null, references listed in a documentation node
  • Caveat => a list, default value null, warnings or limitations listed in a documentation node
  • SeeAlso => a list, default value null, cross-references to other documentation nodes
  • Subnodes => a list, default value null, a menu of documentation nodes
  • SourceCode => a list, default value null, sources displayed in a documentation node
  • ExampleFiles => a list, default value null, data files corresponding to a documentation node
• Consequences:

  • formatted documentation is created and stored in the current package

Description

    document {
        Key          => {myFunc, (myFunc, MyType), [myFunc, MyOption], ...},
        Headline     => "one line description of myFunc", -- not needed for overviews
        BaseFunction => myFunc, -- usually not needed
        Usage        => "myFunc x",
        Inputs       => { inputs, ... },
        Outputs      => { outputs, ... },
        SourceCode   => { METHOD1, ... }, -- usually not needed
        Consequences => { side-effects, ... },
        "A list of strings containing names of files in the auxiliary
        directory of the package can go here; the files will be visible
        in the current directory while example code is run.",
        ExampleFiles => {"datafile1", "datafile2"},
        "There can be explanatory prose here in the form of a hypertext list.",
        EXAMPLE lines ///
          m2code
          m2code
          m2code
        ///,
        "There can be explanatory prose here in the form of a hypertext list.",
        Caveat       => {"warning"},
        SeeAlso      => {"other things"},
        Subnodes     => {
            "subheading a",
            TO "node 1",
            TO "node 2",
            "subheading b",
            TO "node 3",
            ...
            },
        }

See also

• writing documentation
• hypertext -- prepare hypertext for display

Menu

Documentation templates based on the hypertext list format

• package documentation template
• function documentation template
• optional argument documentation template
• overview documentation template

Special documentation keywords

• document(...,Key=>...) -- see Key -- key of a documentation node
• document(...,Headline=>...) -- see Headline -- headline of a documentation node
• document(...,BaseFunction=>...) -- see BaseFunction -- the basename of a function in a documentation node
• document(...,Usage=>...) -- see Usage -- ways to use a function in a documentation node
• document(...,Inputs=>...) -- see Inputs -- inputs for a function in a documentation node
• document(...,Outputs=>...) -- see Outputs -- outputs for a function in a documentation node
• document(...,Consequences=>...) -- see Consequences -- side-effects of a function in a documentation node
• document(...,Acknowledgement=>...) -- see Acknowledgement -- acknowledgements listed in a documentation node
• document(...,Contributors=>...) -- see Contributors -- non-author contributors listed in a documentation node
• document(...,References=>...) -- see References -- references listed in a documentation node
• document(...,Caveat=>...) -- see Caveat -- warnings or limitations listed in a documentation node
• document(...,SeeAlso=>...) -- see SeeAlso -- cross-references to other documentation nodes
• document(...,Subnodes=>...) -- see Subnodes -- a menu of documentation nodes
• document(...,SourceCode=>...) -- see SourceCode -- sources displayed in a documentation node
• document(...,ExampleFiles=>...) -- see ExampleFiles -- data files corresponding to a documentation node