doc.jam

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

        Use --help $(module-name).<variable-name> to get more information. ;
    
    # Print out all the same information but indetailed form.
    if $(.option.detailed)
    {
        print-help-classes $(module-name) ;
        print-help-rules $(module-name) ;
        print-help-variables $(module-name) ;
    }
}

# Generate documentation for a set of rules in a module.
#
local rule print-help-rules (
    module-name # Module of the rules.
    : name * # Optional list of rules to describe.
    )
{
    name ?= $($(module-name).rules) ;
    if [ set.intersection $(name) : $($(module-name).rules) $($(module-name).class-rules) ]
    {
        # Print out the given rules.
        for local rule-name in [ sequence.insertion-sort $(name) ]
        {
            if $(.option.show-locals) || ! $($(module-name).$(rule-name).is-local)
            {
                local signature = $($(module-name).$(rule-name).signature:J=" ") ;
                signature ?= "" ;
                print.section "Rule '$(module-name).$(rule-name) ( $(signature) )'"
                    $($(module-name).$(rule-name).docs) ;
                if $($(module-name).$(rule-name).args)
                {
                    print.list-start ;
                    for local arg-name in $($(module-name).$(rule-name).args)
                    {
                        print.list-item $(arg-name): $($(module-name).$(rule-name).args.$(arg-name).docs) ;
                    }
                    print.list-end ;
                }
            }
        }
    }
}

# Generate documentation for a set of classes in a module.
#
local rule print-help-classes (
    module-name # Module of the classes.
    : name * # Optional list of classes to describe.
    )
{
    name ?= $($(module-name).classes) ;
    if [ set.intersection $(name) : $($(module-name).classes) ]
    {
        # Print out the given classes.
        for local class-name in [ sequence.insertion-sort $(name) ]
        {
            if $(.option.show-locals) || ! $($(module-name).$(class-name).is-local)
            {
                local signature = $($(module-name).$(class-name).signature:J=" ") ;
                signature ?= "" ;
                print.section "Class '$(module-name).$(class-name) ( $(signature) )'"
                    $($(module-name).$(class-name).docs)
                   "Inherits from '"$($(module-name).$(class-name).super-name)"'." ;
                if $($(module-name).$(class-name).args)
                {
                    print.list-start ;
                    for local arg-name in $($(module-name).$(class-name).args)
                    {
                        print.list-item $(arg-name): $($(module-name).$(class-name).args.$(arg-name).docs) ;
                    }
                    print.list-end ;
                }
            }
            
            # Print out the documented rules of the class.
            print-help-module-section $(module-name) $(class-name).class-rules : "Class '$(module-name).$(class-name)' rules"
                Use --help $(module-name).<rule-name> to get more information. ;
            
            # Print out all the rules if details are requested.
            if $(.option.detailed)
            {
                print-help-rules $(module-name) : $($(module-name).$(class-name).class-rules) ;
            }
        }
    }
}

# Generate documentation for a set of variables in a module.
#
local rule print-help-variables (
    module-name ? # Module of the variables.
    : name * # Optional list of variables to describe.
    )
{
    name ?= $($(module-name).variables) ;
    if [ set.intersection $(name) : $($(module-name).variables) ]
    {
        # Print out the given variables.
        for local variable-name in [ sequence.insertion-sort $(name) ]
        {
            print.section "Variable '$(module-name).$(variable-name)'" $($(module-name).$(variable-name).docs) ;
            if $($(module-name).$(variable-name).default) ||
                $($(module-name).$(variable-name).initial)
            {
                print.list-start ;
                if $($(module-name).$(variable-name).default)
                {
                    print.list-item "default value:" '$($(module-name).$(variable-name).default:J=" ")' ;
                }
                if $($(module-name).$(variable-name).initial)
                {
                    print.list-item "initial value:" '$($(module-name).$(variable-name).initial:J=" ")' ;
                }
                print.list-end ;
            }
        }
    }
}

local rule __test__
{
}

ws = "	 " ;

# Extract the text from a block of comments.
#
local rule extract-comment (
    var # The name of the variable to extract from.
    )
{
    local comment = ;
    local line = $($(var)[1]) ;
    local l = [ MATCH "^[$(ws)]*(#)(.*)$" : $(line) ] ;
    while $(l[1]) && $($(var))
    {
        if $(l[2]) { comment += [ MATCH "^[$(ws)](.*)$" : $(l[2]) ] ; }
        else { comment += "" ; }
        $(var) = $($(var)[2-]) ;
        line = $($(var)[1]) ;
        l = [ MATCH "^[$(ws)]*(#)(.*)$" : $(line) ] ;
    }
    return $(comment) ;
}

# Extract s single line of Jam syntax, ignoring any comments.
#
local rule extract-syntax (
    var # The name of the variable to extract from.
    )
{
    local syntax = ;
    local line = $($(var)[1]) ;
    while ! $(syntax) && ! [ MATCH "^[$(ws)]*(#)" : $(line) ] && $($(var))
    {
        local m = [ MATCH "^[$(ws)]*(.*)$" : $(line) ] ;
        if $(m) && ! $(m) = ""
        {
            syntax = $(m) ;
        }
        $(var) = $($(var)[2-]) ;
        line = $($(var)[1]) ;
    }
    return $(syntax) ;
}

# Extract the next token, this is either a single Jam construct
# or a comment as a single token.
#
local rule extract-token (
    var # The name of the variable to extract from.
    )
{
    local parts = ;
    while ! $(parts)
    {
        parts = [ MATCH "^[$(ws)]*([^$(ws)]+)[$(ws)]*(.*)" : $($(var)[1]) ] ;
        if ! $(parts)
        {
            $(var) = $($(var)[2-]) ;
        }
    }
    local token = ;
    if [ MATCH "^(#)" : $(parts[1]) ]
    {
        token = $(parts:J=" ") ;
        $(var) = $($(var)[2-]) ;
    }
    else
    {
        token = $(parts[1]) ;
        $(var) = $(parts[2-]:J=" ") $($(var)[2-]) ;
    }
    return $(token) ;
}

# Scan for a rule declaration as the next item in the variable.
#
local rule scan-rule (
    syntax ? # The first part of the text which contains the rule declaration.
    : var # The name of the variable to extract from.
    )
{
    local rule-parts =
        [ MATCH "^[$(ws)]*(rule|local[$(ws)]*rule)[$(ws)]+([^$(ws)]+)[$(ws)]*(.*)" : $(syntax:J=" ") ] ;
    if $(rule-parts[1])
    {
        # mark as doc for rule.
        local rule-name = $(rule-parts[2]) ;
        if $(scope-name)
        {
            rule-name = $(scope-name).$(rule-name) ;
        }
        local is-local = [ MATCH "^(local).*" : $(rule-parts[1]) ] ;
        if $(comment-block)
        {
            set-rule-doc $(rule-name) $(module-name) $(is-local) : $(comment-block) ;
        }
        # parse args of rule.
        $(var) = $(rule-parts[3-]) $($(var)) ;
        set-rule-arguments-signature $(rule-name) $(module-name) : [ scan-rule-arguments $(var) ] ;
        # scan within this rules scope.
        local scope-level = [ extract-token $(var) ] ;
        local scope-name = $(rule-name) ;
        while $(scope-level)
        {
            local comment-block = [ extract-comment $(var) ] ;
            local syntax-block = [ extract-syntax $(var) ] ;
            if [ scan-rule $(syntax-block) : $(var) ]
            {
            }
            else if [ MATCH "^(\\{)" : $(syntax-block) ]
            {
                scope-level += "{" ;
            }
            else if [ MATCH "^[^\\}]*([\\}])[$(ws)]*$"  : $(syntax-block) ]
            {
                scope-level = $(scope-level[2-]) ;
            }
        }
        
        return true ;
    }
}

# Scan the arguments of a rule.
#
local rule scan-rule-arguments (
    var # The name of the variable to extract from.
    )
{
    local arg-syntax = ;
    local token = [ extract-token $(var) ] ;
    while $(token) != "(" && $(token) != "{"
    {
        token = [ extract-token $(var) ] ;
    }
    if $(token) != "{"
    {
        token = [ extract-token $(var) ] ;
    }
    local arg-signature = ;
    while $(token) != ")" && $(token) != "{"
    {
        local arg-name = ;
        local arg-qualifier = " " ;
        local arg-doc = ;
        if $(token) = ":"
        {
            arg-signature += $(token) ;
            token = [ extract-token $(var) ] ;
        }
        arg-name = $(token) ;
        arg-signature += $(token) ;
        token = [ extract-token $(var) ] ;
        if [ MATCH "^([\\*\\+\\?])" : $(token) ]
        {
            arg-qualifier = $(token) ;
            arg-signature += $(token) ;
            token = [ extract-token $(var) ] ;
        }
        if $(token) = ":"
        {
            arg-signature += $(token) ;
            token = [ extract-token $(var) ] ;
        }
        if [ MATCH "^(#)" : $(token) ]
        {
            $(var) = $(token) $($(var)) ;
            arg-doc = [ extract-comment $(var) ] ;
            token = [ extract-token $(var) ] ;
        }
        set-argument-doc $(arg-name) $(arg-qualifier) $(rule-name) $(module-name) : $(arg-doc) ;
    }
    while $(token) != "{"
    {
        token = [ extract-token $(var) ] ;
    }
    $(var) = "{" $($(var)) ;
    arg-signature ?= "" ;
    return $(arg-signature) ;
}

# Scan for a variable declaration.
local rule scan-variable (
    syntax ? # The first part of the text which contains the variable declaration.
    : var # The name of the variable to extract from.
    )
{
    # [1] = name, [2] = value(s)
    local var-parts =
        [ MATCH "^[$(ws)]*([^$(ws)]+)[$(ws)]+([\\?\\=]*)[$(ws)]+([^\\;]*)\\;" : $(syntax) ] ;
    if $(var-parts)
    {
        local value = [ MATCH "^(.*)[ ]$" : $(var-parts[3-]:J=" ") ] ;
        local default-value = "" ;
        local initial-valie = "" ;
        if $(var-parts[2]) = "?="
        {
            default-value = $(value) ;
            default-value ?= "(empty)" ;
        }
        else
        {
            initial-value = $(value) ;
            initial-value ?= "(empty)" ;
        }
        if $(comment-block)
        {
            set-variable-doc $(var-parts[1]) $(default-value) $(initial-value) $(module-name) : $(comment-block) ;
        }
        return true ;
    }
}

# Scan a class declaration.
local rule scan-class (
    syntax ? # The syntax text for the class declaration.
    )
{
    # [1] = class?, [2] = name, [3] = superclass
    local class-parts =
        [ MATCH "^[$(ws)]*([^$(ws)]+)[$(ws)]+([^$(ws)]+)[$(ws)]+:*[$(ws)]*([^$(ws);]*)" : $(syntax) ] ;
    if $(class-parts[1]) = "class" || $(class-parts[1]) = "class.class"
    {
        set-class-doc $(class-parts[2]) $(module-name) : $(class-parts[3]) ;
    }
}

# Scan a module file for documentation comments. This also
# invokes any actions assigned to the module. The actions
# are the rules that do the actual output of the documentation.
# This rue is invoked as the header scan rule for the module file.
#
rule scan-module (
    target # The module file.
    : text * # The text in the file, one item per line.
    : binding
    )
{    
    if $(.option.debug) { ECHO "HELP:" scanning module target '$(target)' ; }
    local module-name = $(.module<$(target)>.name) ;
    local module-documented = ;
    local comment-block = ;
    local syntax-block = ;
    # This is a hack because we can't get the line of a file if it
    # happens to not have a new-line termination.
    text += "}" ;
    while $(text)
    {
        comment-block = [ extract-comment text ] ;
        syntax-block = [ extract-syntax text ] ;
        if $(.option.debug)
        {
            ECHO "HELP:" comment block; '$(comment-block)' ;
            ECHO "HELP:" syntax block; '$(syntax-block)' ;
        }
        if [ scan-rule $(syntax-block) : text ] { }
        else if [ scan-variable $(syntax-block) : text ] { }
        else if [ scan-class $(syntax-block) ] { }
        else if [ MATCH .*([cC]opyright).* : $(comment-block:J=" ") ]
        {
            # mark as the copy for the module.
            set-module-copyright $(module-name) : $(comment-block) ;
        }
        else if ! $(module-documented)
        {
            # document the module.
            set-module-doc $(module-name) : $(comment-block) ;
            module-documented = true ;
        }
    }
    for local action in $(.module<$(target)>.actions)
    {
        local action-rule = [ $(action).front ] ; $(action).pop-front ;
        local action-args = [ $(action).get ] ;
        local ignored = [ $(action-rule) $(module-name) : $(action-args) ] ;
    }
}

# Import scan-module to global scope, so that it's available during
# header scanning phase.
IMPORT $(__name__) : scan-module : : doc.scan-module ;


# Add a scan action to perform to generate the help documentation.
# The action rule is passed the name of the module as the first argument.
# The second argument(s) are optional and passed directly as specified
# here.
#
local rule do-scan (
    modules + # The modules to scan and perform the action on.
    : action * # The action rule, plus the secondary arguments to pass to the action rule.
    )
{
    local targets = ;
    for local module-file in $(modules)
    {
        local module-name = $(module-file:B) ;
        .module<$(module-file)>.name = $(module-name) ;
        if $(action)
        {
            .module<$(module-file)>.actions += [ class.new vector $(action) ] ;
        }
        HDRSCAN on $(module-file) = "^(.*).$" ;
        HDRRULE on $(module-file) = doc.scan-module ;
        NOTFILE $(module-name).scan ;
        ALWAYS $(module-name).scan ;
        INCLUDES $(module-name).scan : $(module-file) ;
        targets += $(module-name).scan ;
    }
    if $(help-output) = console
    {
        DEPENDS all : $(targets) ;
    }
    if $(help-output) = text
    {
        print.output $(help-output-file).txt plain ;
        ALWAYS $(help-output-file).txt ;
        DEPENDS $(help-output-file).txt : $(targets) ;
        DEPENDS all : $(help-output-file).txt ;
    }
    if $(help-output) = html
    {
        print.output $(help-output-file).html html ;
        ALWAYS $(help-output-file).html ;
        DEPENDS $(help-output-file).html : $(targets) ;
        DEPENDS all : $(help-output-file).html ;
    }
}