McXtrace includes a facility called MxDoc to help maintain documentation of components and instruments. In the source code, comments may be written that follow a particular format understood by MxDoc. The MxDoc facility will read these comments and automatically produce output documentation in various forms. By using the source code itself as the source of documentation, the documentation is much more likely to be a faithful and up-to-date description of how the component/instrument actually works.
Two forms of documentation can be generated. One is the component entry dialog in the mxgui front-end, see section 5.4.1. The other is a collection of web pages documenting the components and instruments, handled via the mxdoc front-end (see section 5.4.6), and the complete documentation for all available McXtrace components and instruments may be found at the McXtrace webpage [Mcx], as well as in the McXtrace library (see 7.1). All available McXtrace documentation is accessible from the mxgui ’Help’ menu.
Note that MxDoc-compliant comments in the source code are no substitute for a good reference manual entry. The mathematical equations describing the physics and algorithms of the component should still be written up carefully for inclusion in the component manual. The MxDoc comments are useful for describing the general behaviour of the component, the meaning and units of the input parameters, etc.
The format of the comments understood by MxDoc is mostly straight-forward, and is designed to be easily readable both by humans and by automatic tools. MxDoc has been written to be quite tolerant in terms of how the comments may be formatted and broken across lines. A good way to get a feeling for the format is to study some of the examples in the existing components and instruments. Below, a few notes are listed on the requirements for the comment headers:
The comment syntax uses %IDENTIFICATION, %DESCRIPTION, %PARAMETERS, %EXAMPLE:, %LINKS, and %END keywords to mark different sections of the documentation. Keywords may be abbreviated (except for %EXAMPLE:), e.g. as %IDENT or %I.
Additionally, optional keys %VALIDATION and %BUGS may be found to list validation status and possible bugs in the component.
In the %IDENTIFICATION section, author: (or written by: for backwards compatibility with old comments) denote author; date:, version:, and origin: are also supported. Any number of Modified by: entries may be used to give the revision history. The author:, date:, etc. entries must all appear on a single line of their own. Everything else in the identification section is part of a ”short description” of the component.
In the %PARAMETERS section, descriptions have the form “name: [unit] text ” or “name: text [unit]”. These may span multiple lines, but subsequent lines must be indented by at least four spaces. Note that square brackets [] should be used for units. Normal parentheses are also supported for backwards compatibility, but nested parentheses do not work well.
The %DESCRIPTION section contains text in free format. The text may contain HTML tags like <IMG> (to include pictures) and <A>…</A> (for links to other web pages, but see also the %LINK section). In the generated web documentation pages, the text is set in <PRE>…</PRE>, so that the line breaks in the source will be obeyed.
The %EXAMPLE: lines in instrument headers indicate an example parameter set or command that may be run to test the instrument. A following Detector: <name>_I=<value> indicates what value should be obtained for a given monitor. More than one example line may be specified in instruments.
Any number of %LINK sections may be given; each one contains HTML code that will be put in a list item in the link section of the description web page. This usually consists of an <A HREF="..."> ... </A> pointer to some other source of information.
Optionally, an %INSTRUMENT_SITE section followed by a single word is used to sort instruments by origin/location in the ’X-ray Site’ menu in mxgui.
After %END, no more comment text is read by MxDoc.