doc.jam

C++的一个好库。。。现在很流行

# (C) Copyright Rene Rivera, 2002-2003.
#
# See accompanying license for terms and conditions of use.
#

# Documentation system, handles --help requests.
# It defines rules that attach documentation to modules, rules, and variables.
# Collects and generates documentation for the various parts of the build system.
# The documentation is collected from comments integrated into the code.

import modules ;
import print ;
import set ;
import container ;
import "class" ;
import sequence ;

# The type of output to generate.
# "console" is formated text echoed to the console (the default);
# "text" is formated text appended to the output file;
# "html" is HTML output to the file.
#
help-output = console ;

# The file to output documentation to when generating "text" or "html"
# help. This is without extension as the extension is determined by the
# type of output.
#
help-output-file = help ;

# Whether to include local rules in help output.
#
.option.show-locals ?= ;

# When showing documentation for a module, whether to also generate
# automatically the detailed docs for each item in the module.
#
.option.detailed ?= ;

# Generate debug output as the help is generated and modules
# are parsed.
#
.option.debug ?= ;

# Enable or disable a documentation option.
#
local rule set-option (
    option # The option name.
    : value ? # Enabled (non-empty), or disabled (empty)
    )
{
    .option.$(option) = $(value) ;
}

# Set the type of output.
#
local rule set-output (
    type
    )
{
    help-output = $(type) ;
}

# Set the output to a file.
#
local rule set-output-file (
    file
    )
{
    help-output-file = $(file) ;
}

# Extracts the brief comment from a complete comment. The brief
# comment is the first sentence.
#
local rule brief-comment (
    docs * # The comment documentation.
    )
{
    local d = $(docs:J=" ") ;
    local p = [ MATCH ".*([.])$" : $(d) ] ;
    if ! $(p) { d = $(d)"." ; }
    d = $(d)" " ;
    local m = [ MATCH "^([^.]+[.])(.*)" : $(d) ] ;
    local brief = $(m[1]) ;
    while $(m[2]) && [ MATCH "^([^ ])" : $(m[2]) ]
    {
        m = [ MATCH "^([^.]+[.])(.*)" : $(m[2]) ] ;
        brief += $(m[1]) ;
    }
    return $(brief:J="") ;
}

# Specifies the documentation for the current module.
#
local rule set-module-doc (
    module-name ? # The name of the module to document.
    : docs * # The documentation for the module.
    )
{
    module-name ?= * ;

    $(module-name).brief = [ brief-comment $(docs) ] ;
    $(module-name).docs = $(docs) ;

    if ! $(module-name) in $(documented-modules)
    {
        documented-modules += $(module-name) ;
    }
}

# Specifies the documentation for the current module.
#
local rule set-module-copyright (
    module-name ? # The name of the module to document.
    : copyright * # The copyright for the module.
    )
{
    module-name ?= * ;

    $(module-name).copy-brief = [ brief-comment $(copyright) ] ;
    $(module-name).copy-docs = $(docs) ;

    if ! $(module-name) in $(documented-modules)
    {
        documented-modules += $(module-name) ;
    }
}

# Specifies the documentation for a rule in the current module.
# If called in the global module, this documents a global rule.
#
local rule set-rule-doc (
    name # The name of the rule.
    module-name ? # The name of the module to document.
    is-local ? # Whether the rule is local to the module.
    : docs * # The documentation for the rule.
    )
{
    module-name ?= * ;

    $(module-name).$(name).brief = [ brief-comment $(docs) ] ;
    $(module-name).$(name).docs = $(docs) ;
    $(module-name).$(name).is-local = $(is-local) ;

    if ! $(name) in $($(module-name).rules)
    {
        $(module-name).rules += $(name) ;
    }
}

# Specify a class, will turn a rule into a class.
#
local rule set-class-doc (
    name # The name of the class.
    module-name ? # The name of the module to document.
    : super-name ? # The super class name.
    )
{
    module-name ?= * ;

    $(module-name).$(name).is-class = true ;
    $(module-name).$(name).super-name = $(super-name) ;
    $(module-name).$(name).class-rules =
        [ MATCH "^($(name)[.].*)" : $($(module-name).rules) ] ;
    $(module-name).$($(module-name).$(name).class-rules).is-class-rule = true ;

    $(module-name).classes += $(name) ;
    $(module-name).class-rules += $($(module-name).$(name).class-rules) ;
    $(module-name).rules =
        [ set.difference $($(module-name).rules) :
            $(name) $($(module-name).$(name).class-rules) ] ;
}

# Set the argument call signature of a rule.
#
local rule set-rule-arguments-signature (
    name # The name of the rule.
    module-name ? # The name of the module to document.
    : signature * # The arguments signature.
    )
{
    module-name ?= * ;

    $(module-name).$(name).signature = $(signature) ;
}

# Specifies the documentation for an argument of a rule.
#
local rule set-argument-doc (
    name # The name of the argument.
    qualifier # Argument syntax qualifier, "*", "+", etc.
    rule-name # The name of the rule.
    module-name ? # THe optional name of the module.
    : docs * # The documentation.
    )
{
    module-name ?= * ;

    $(module-name).$(rule-name).args.$(name).qualifier = $(qualifier) ;
    $(module-name).$(rule-name).args.$(name).docs = $(docs) ;

    if ! $(name) in $($(module-name).$(rule-name).args)
    {
        $(module-name).$(rule-name).args += $(name) ;
    }
}

# Specifies the documentation for a variable in the current module.
# If called in the global module, the global variable is documented.
#
local rule set-variable-doc (
    name # The name of the variable.
    default # The default value.
    initial # The initial value.
    module-name ? # The name of the module to document.
    : docs * # The documentation for the variable.
    )
{
    module-name ?= * ;

    $(module-name).$(name).brief = [ brief-comment $(docs) ] ;
    $(module-name).$(name).default = $(default) ;
    $(module-name).$(name).initial = $(initial) ;
    $(module-name).$(name).docs = $(docs) ;

    if ! $(name) in $($(module-name).variables)
    {
        $(module-name).variables += $(name) ;
    }
}

# Generates a general description of the documentation and help system.
#
local rule print-help-top ( )
{
    print.section "Available Help"
        These are the available options for obtaining documentation.
        Some options have additional instructions on how to get more
        detailed information. Multiple options are allowed and
        sometimes required. For example, the options that configure
        the help system still require a regular help request option
        for any output to be generated.
        ;
    print.list-start ;
    print.list-item --help; This help message. ;
    print.list-item --help-usage; How to invoke '"bjam".' ;
    print.list-item --help-all; Brief information on available modules. ;
    print.list-item --help <module-name>; Get information about a module. ;
    print.list-item --help-options; Options for controlling the help display. ;
    print.list-item --help-output <type>; The type of output to genetare.
        '"console" is formated text echoed to the console (the default);'
        '"text" is formated text appended to the output file;'
        '"html" is HTML output to the file.' ;
    print.list-item --help-output-file <file>; The file to output the documentation. ;
    print.list-end ;
}

# Generate Jam/Boost.Jam command usage information.
#
local rule print-help-usage ( )
{
    print.section "Boost.Jam Usage"
        "bjam [ options... ] targets..."
        ;
    print.list-start ;
    print.list-item -a;
        Build all targets, even if they are current. ;
    print.list-item -fx;
        Read '"x"' as the Jamfile for building instead of searching
        for the Boost.Build system. ;
    print.list-item -jx;
        Run up to '"x"' commands concurrently. ;
    print.list-item -n;
        Do not execute build commands. Instead print out the commands
        as they would be executed if building. ;
    print.list-item -ox;
        Write the build commands to the file '"x"'. ;
    print.list-item -q;
        Quit as soon as the build of a target fails. Specifying this prevents the
        attempt of building as many targets as possible regardless of failures. ;
    print.list-item -sx=y;
        Sets a Jam variable '"x"' to the value '"y"', overriding any value that
        variable would have from the environment. ;
    print.list-item -tx;
        Rebuild the target '"x"', even if it is up-to-date. ;
    print.list-item -v;
        Display the version of bjam. ;
    print.list-item --x;
        Option '"x"' is ignored but considered and option. The option is then
        available from the '"ARGV"' variable. ;
    print.list-item -dn;
        Enables output of diagnostic messages. The debug level '"n"' and all
        below it are enabled by this option. ;
    print.list-item -d+n;
        Enables output of diagnostic messages. Only the output for debug level '"n"'
        is enabled. ;
    print.list-end ;
    print.section "Debug Levels"
        Each debug level shows a different set of information. Usually with the higher
        levels producing more verbose information. The following levels are supported:
        ;
    print.list-start ;
    print.list-item 0;
        Turn off all diagnostic output. Only errors are reported. ;
    print.list-item 1;
        Show the actions taken for building targets, as they are executed. ;
    print.list-item 2;
        Show "quiet" actions and display all action text, as they are executed. ;
    print.list-item 3;
        Show dependency analysis, and target/source timestamps/paths. ;
    print.list-item 4;
        Show arguments of shell invocations. ;
    print.list-item 5;
        Show rule invocations and variable expansions. ;
    print.list-item 6;
        Show directory/header file/archive scans, and attempts at binding to targets. ;
    print.list-item 7;
        Show variable settings. ;
    print.list-item 8;
        Show variable fetches, variable expansions, and evaluation of '"if"' expressions. ;
    print.list-item 9;
        Show variable manipulation, scanner tokens, and memory usage. ;
    print.list-item 10;
        Show execution times for rules. ;
    print.list-item 11;
        Show parsing progress of Jamfiles. ;
    print.list-item 12;
        Show graph for target dependencies. ;
    print.list-item 13;
        Show changes in target status (fate). ;
    print.list-end ;
}

# Generates description of options controlling the help system.
# This automatically reads the options as all variables in the doc
# module of the form ".option.*".
#
local rule print-help-options (
    module-name # The doc module.
    )
{
    print.section "Help Options"
        These are all the options available for enabling or disabling
        to control the help system in various ways. Options can be enabled
        or disabled with '"--help-enable-<option>"', and "'--help-disable-<option>'"
        respectively.
        ;
    local options-to-list = [ MATCH ^[.]option[.](.*) : $($(module-name).variables) ] ;
    if $(options-to-list)
    {
        print.list-start ;
        for local option in [ sequence.insertion-sort $(options-to-list) ]
        {
            local def = disabled ;
            if $($(module-name)..option.$(option).default) != "(empty)"
            {
                def = enabled ;
            }
            print.list-item $(option): $($(module-name)..option.$(option).docs)
                Default is $(def). ;
        }
        print.list-end ;
    }
}

# Generate brief documentation for all the known items in the section
# for a module. Possible sections are: "rules", and "variables".
#
local rule print-help-module-section (
    module # The module name.
    section # rules or variables.
    : section-head # The title of the section.
    section-description * # The detailed description of the section.
    )
{
    if $($(module).$(section))
    {
        print.section $(section-head) $(section-description) ;
        print.list-start ;
        for local item in [ sequence.insertion-sort $($(module).$(section)) ]
        {
            local show = ;
            if ! $($(module).$(item).is-local)
            {
                show = yes ;
            }
            if $(.option.show-locals)
            {
                show = yes ;
            }
            if $(show)
            {
                print.list-item $(item): $($(module).$(item).brief) ;
            }
        }
        print.list-end ;
    }
}

# Generate documentation for possible modules. We attempt to list all known
# modules, and a brief description of each.
#
local rule print-help-all (
    ignored # Usually the module name, but is ignored here.
    )
{
    print.section "Modules"
        "These are all the known modules. Use --help <module> to get more"
        "detailed information."
        ;
    if $(documented-modules)
    {
        print.list-start ;
        for local module-name in [ sequence.insertion-sort $(documented-modules) ]
        {
            # The brief docs for each module.
            print.list-item $(module-name): $($(module-name).brief) ;
        }
        print.list-end ;
    }
    # The documentation for each module when details are requested.
    if $(documented-modules) && $(.option.detailed)
    {
        for local module-name in [ sequence.insertion-sort $(documented-modules) ]
        {
            # The brief docs for each module.
            print-help-module $(module-name) ;
        }
    }
}

# Generate documentation for a module. Basic information about
# the module is generated.
#
local rule print-help-module (
    module-name # The module to generate docs for.
    )
{
    # Print the docs.
    print.section "Module '$(module-name)'" $($(module-name).docs) ;
    
    # Print out the documented classes.
    print-help-module-section $(module-name) classes : "Module '$(module-name)' classes"
        Use --help $(module-name).<class-name> to get more information. ;
    
    # Print out the documented rules.
    print-help-module-section $(module-name) rules : "Module '$(module-name)' rules"
        Use --help $(module-name).<rule-name> to get more information. ;
    
    # Print out the documented variables.
    print-help-module-section $(module-name) variables : "Module '$(module-name)' variables"