Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Draft Change Proposals Up: NOTE 243 - XML-based Documentation for AIPS++ Previous: Conclusions

Example of In-line Documentation Markup

The following example is provided to give the flavor of in-line documentation proposed through this note. It does not contain all the tags expected to be supported nor all the documentation that should be included as a matter of style. However, it should illustrate the basic structure of the in-line documentation and how certain information can be assume by the comments context.

pragma include once;

include 'unset.g';
include 'xmlstorage.g';

#@tool 
# Buffer for building an element using "easy" storage.  
# 
# This tool is used for loading XML data into a metadata storage
# object which can be returned with a call to 
# <tmlink>getelementrep</tmlink>.  The storage model supported by this
# buffer is optimized for access to XML data from the application/user 
# level.  XML Elements are stored as Glish records, and their attributes,
# as Glish attributes.  
# 
# @constructor
# create an "easy" element buffer.
# @inparam element  previously built element to edit
#                   @type record
#                   @default unset  create a new element
xmleasyelementbuf := function(ref element=unset) {

    #@toolrec public
    public := _xmlstorage();
    private := [=];

    #@
    # set the name of the element
    # @inparam elname  the element name.  This must begin with a letter
    #                  and should should not end in a number.
    #                  @type string
    #                  @default none
    # @inparam clear   if true, clear all previously added data
    # 
    public.setname := function(elname, clear=T) {
        # ...
    }

    #@ 
    # get the name of the top element in this buffer
    public.getname := function() {
        # ...
    }

    #@
    # set an attribute value
    # @inparam attname   the attribute name.  The name must begin with 
    #                   a letter.
    #                   @type string
    # @inparam value    the value of the attribute
    # @inparam default  if true, this value should be considered a default.
    #                   This can used to affect conversion to XML--e.g. one
    #                   may not want to have attributes with default values
    #                   printed out.
    public.setattribute := function(attname, value='', default=F) {
        # ...
    }

    #@ 
    # add some text to the value of the current element
    # @param  text     the text to add
    #                  @type any
    #                  @default an empty string
    # @param  which    replace the which-th text value, if it exists;
    #                  otherwise, just add it.
    #                  @default 0, which means append a new processing 
    #                           instruction
    # @fail if input text is not a string
    public.addText := function(text='', which=0) {
        # ...
    }

    #@
    # return a the buffer of a child element for editing
    # @param elname   the child element name.  If the element has not
    #                 yet been added, it will be.
    # @param  which    replace the which-th element, if it exists;
    #                  otherwise, just add it.
    # @return tool of type xmleasystorage 
    public.getChildElementBuf := function(elname, which=0) {
        # ...
    }

    #@
    # return a copy of the constructed element record 
    # @param options  a record containing options for formatting the
    #                 element representation.  Currently supported
    #		      options include:
    # <pre>                
    #        cleanup  if true, element content will be adjusted to aid in 
    #                 user access.  All non-element children of the same type 
    #                 (text, comments, or processing instructions) adjacent
    #                 to each other will be gathered into a single array.
    #                 Furthermore, if an element contains only text child 
    #                 nodes, the element's children will be "pulled up"--that 
    #                 id, replaced with a single array containing all the text
    #                 node values.  The default is T.
    #        nopullup a list of elements whose child text nodes should not be
    #                 "pulled up" as described above.  This might contain a 
    #                 list of elements that can but not always contain mixed
    #                 (elements and text) content.  
    # </pre>
    # @return the storage object in the form of a Glish record
    public.getElementRep := function(val options) {
        # ... 
    }


    #@
    # shut down this tool
    public.done := function() {
        # ... 
    }

    # ...

    return ref public;
}

Next: Draft Change Proposals Up: NOTE 243 - XML-based Documentation for AIPS++ Previous: Conclusions Contents