SMLDoc -- Document Generator for Standard ML

@author YAMATODANI Kiyoshi
@version $Id: OVERVIEW_en.txt,v 1.3 2007/03/27 15:18:23 kiyoshiy Exp $

========================================
1. SMLDoc

 SMLDoc analyzes source file written in Standard ML and generates documents in HTML format which describes about program entities, such as modules, bindings and types in HTML format.


========================================
2. doc comment

 Description about a program entity is put in the comment just ahead of the declaration of the entity enclosed with "(**" and "*)". These comments are called 'doccomment'.


====================
2.1. sections

 A doccomment consists of summary section, detail section and tag section. The summary section contains summary description about the entity. The detail section contains detail description about the entity. The tag section contains attributes of the entity.

 The summary section is required. The detail section can be omitted. The tag section also can be omitted.
 Sections are ordered as summary section, detail section and tag section. The tag section starts at the first line which begins by a '@' character.

  (**
   * summary of the entity.
   * detail of the entity
   *    :
   * @tag desciption
   *    :
   *)


====================
2.2. tag

 Following tags are supported. Specification of each tag is same as those of JavaDoc.

@author  author of the entity
@copyright copyright
@contributor contributor
{@docRoot} a link to the top directory where documents are generated (not implemented)
@exception indicates an exception the entity (a function) may raises
{@link}  a hyperlink (not implemented)
@params  gives names to formal parameters of functions and value constructors
@param   a description of a formal parameter
@return  a description about return value of the function
@see     related items (specified text is not analyzed in the current version)
@throws  same as the @exception tag
@version a text which indicates the version of the entity



====================
2.2.1. params tag

 @params tag gives names to formal parameters of functions and value constructors. Argument to @params tag is a list of patterns.

  @params pat ... pat

The syntax of patterns is as follows.

  pat ::= ID
        | "(" pat "," ... "," pat ")"
        | "{" patrow "," ... "," patrow "}"

  patrow ::= ID "=" pat
           | ID

 ID occurring in @params tag can be used in @param tags.

 A @param tag describes about an formal parameter to which the ID is given by the @params tag.

  @param ID description


====================
2.3. inline comment

 Descriptions about elements of tuple/record can be written in comments inlined in type expression.

  (**
   * a range between two integer value.
   *)
  type range =
       {
         (** minimum value *) 
         min : int,
         (** maximum value *)
         max : int
       }

  (**
   * opens a file.
   * @return file stream
   *)
  val openFile :
      {
        (** file name *)
        fileName : string,
        (** mode flag *)
        mode : openMode
      } -> stream

 Using @params tag, the above second example can be written as follows.

  (**
   * opens a file.
   * @params {fileName, mode}
   * @param fileName file name
   * @param mode mode flag
   * @return file stream
   *)
  val openFile : {fileName : string, mode : openMode} -> stream


====================
2.3. sample

  ------------------------------------------------------------
  sample1: doccomments for specification
  ------------------------------------------------------------

  (**
   *  The HTML documentation generator.
   *
   *  The documentation generator generates HTML documents about
   * ML entities such as module declarations, value binding, type
   * declarations, etc.
   *  The descriptions of the document is extracted from the
   * doccomments in the source file.
   *
   * @see <a href="http://java.sun.com/j2se/javadoc/index.html">
   *       JavaDoc</a>
   * @see <a href="http://caml.inria.fr/ocaml/htmlman/manual029.html">
   *       OCamlDoc</a>
   * @author YAMATODANI Kiyoshi <kiyoshiy@jaist.ac.jp>
   * @version 1.0
   *)
  signature DOCGENERATOR = 
  sig

    (** CSS rule *)
    type CSSrule = 
    {
      (** selector *)
      selector : string,
      (** name of property *)
      property : string,
      (** value of the property *)
      value : string 
    }

    (**
     * the style of HTML document
     *)
    datatype HTMLstyle =
             Plain (** simple style *)
           | (** rich style *) Rich
           | (**
              * style sheet file specified
              * @params filename
              * @param filename name of the style sheet file to use
              *)
             CustomCSSFile of string
           | (**
              * style sheet
              * @params styles
              * @param styles style rules
              *)
             Custom of CSSrule list

    (**
     *  generates a HTML document about a declaration of ML entity.
     *
     * @params styleSheet sourceFile (declaration, location)
     * @param styleSheet the style sheet to use
     * @param sourceFile the path of the source file which contains
     *                 the declaration.
     * @param declaration the declaration
     * @param location the location of the declaration in the source
     *                 file
     * @return the HTML code
     *)
    val generateDeclarationDoc
        : HTMLstyle -> string -> (decl * (int * int)) -> string

  end
  ------------------------------------------------------------

  ------------------------------------------------------------
  sample2: doccomments for declarations
  ------------------------------------------------------------
  (**
   * The HTML documentation generator implementation.
   *
   * @author YAMATODANI Kiyoshi <kiyoshiy@jaist.ac.jp>
   * @version 1.0
   *)
  structure DocGenerator : DOCGENERATOR = 
  struct

           :

    (*
     *  This is a normal comment,  not a doccomment. 
     *)
    fun generateDeclarationDoc style sourceFile (declaration, location) =
        ...

    (**
     *  generates a HTML document about a value binding.
     *
     * @params styleSheet sourceFile (binding, location)
     * @param styleSheet the style sheet to use
     * @param sourceFile the path of the source file which contains
     *                 the declaration.
     * @param binding the value binding
     * @param location the location of the binding in the source file
     * @return the HTML code
     * @throws InvalidDocCommentException if the doccomment is not
     *                                   valid format.
     * @see Absyn.binding
     *)
    fun generateValBindDoc style sourceFile =
        fn (ValBind(name, type, _), (line, col)) => ...
         | (FunBind(name, type, _), (line, col)) => ...
         | (RecFunBind bindings, loc) => ...

            :

  end
  ------------------------------------------------------------


========================================
3. invokation

====================
3.1. invoke

 The SMLDoc is invoked by executing the smldoc command with command lines as follows.

  smldoc [OPTION ...] [files...]

====================
3.2. input file

 Input files for document generation are
  SML source file
  CM file of SML/NJ


 File name whose extension is not "cm" is regarded as indicating a SML souce file.

 File name whose extension is "cm" is regarded as indicating a CM file. 
Among file names listed in a CM file, file names whose extension is "sml", "sig" or "fun" are regarded as SML source file and processed as input files to document generation. Other file names are ignored. NOTICE: Name of another CM file is also ignored.


====================
3.3. arugment file

 To avoid restriction of shell in the number and the length of command line arguments, a feature to let the SMLDoc read arguments from files is provided. These files in which arguments to the SMLDoc are listed are called 'argument file'. To have the SMLDoc read an argument file, specify -a or --argufile option with the file name.

 In an argument file, any command line arguments including source file names can be listed.
If ,as a parameter of the -a or --argfile option, name of another argument file is specified in the argument file which is being processed, that file is read as an argument file recursively.
If a path name listed in an argument file is a relative path, it is regarded as a relative path to the directory in which the argument file is contained. This is applied to source file name, argument file name, a parameter of --overview option and a directory name as a parameter of --directory option.


====================
3.4. environment substitution

An environment NAME is substituted for a string ${NAME} occurring in command line arguments and argument files.
For example,

  --directory=${PWD}/doc/api

is, assumed that PWD=/home/yamato, replaced with

  --directory=/home/yamato/doc/api


====================
3.5. other SMLDoc specific options

 Following SMLDoc specific options are supported.

--hidebysig
         If the structure to which a document is generated is constrained by
         a signature, among elements of the structure, includes in the
         generated document only those whose specification is described in the
         signature among.

--listsubmodule
         includes in the module list page the modules which are not declared at
        top level .

--stdin
         gets names of source file from the standard input.
        example:

           $ find . -name '*.sml' | smldoc --stdin

--showsummary
         inserts summary section before detail section as JavaDoc does.


====================
3.6. other options

 Other supported command line options are a subset of those of JavaDoc.

--author
        Includes the @author text in the generated docs. 

--bottom=<HTML>
        Include bottom text for each page

-c <charset>, --charset=<charset>
        Charset for cross-platform viewing of generated documentation.

-d <dir>, --directory=<dir>
        Destination directory for output files

--footer=<HTML>
        Include footer text for each page

--header=<HTML>
        Include header text for each page

-h, --help
        Display command line options and exit

--helpfile=<file>
        Include file that help link links to

--link=<url>
        Create links to SMLDoc output at <url>

--linkoffline=<url>@<file>
        Link to docs at <url> using package list at <file>
        Unlike JavaDoc, the URL to link to and the path name of package list
        are connected by '@' without spaces.
        example:

          --linkoffline=../../../SMLPP/doc/api@../../SMLPP/doc/api/module-list

--nohelp
        Do not generate help link

--nonavbar
        Do not generate navigation bar

--noindex
        Do not generate index

--overview=<file>
        Read overview documentation from HTML file

--splitindex
        Split index into one file per letter

-t <text>, --doctitle=<text>
        Include title for the overview page

-v, --verbose
        Output messages about what SMLDoc is doing

--version
        Include @version paragraphs

-w <text>, --windowtitle=<text>
        Browser window title for the documenation


========================================
References

Javadoc
http://java.sun.com/j2se/javadoc/

OCamlDoc
http://caml.inria.fr/ocaml/htmlman/manual029.html

Haddoc
http://www.haskell.org/haddock/

HDoc
http://www.fmi.uni-passau.de/~groessli/hdoc/

ML-Doc
http://people.cs.uchicago.edu/~jhr/tools/ml-doc.html

============================================================