| # Copyright 2002, 2005 Dave Abrahams |
| # Copyright 2002, 2003, 2006 Rene Rivera |
| # Copyright 2003 Vladimir Prus |
| # Distributed under the Boost Software License, Version 1.0. |
| # (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) |
| |
| # 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 ; |
| import path ; |
| |
| |
| # 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 "General command line usage" ; |
| |
| print.text " bjam [options] [properties] [targets] |
| |
| Options, properties and targets can be specified in any order. |
| " ; |
| |
| print.section "Important Options" ; |
| |
| print.list-start ; |
| print.list-item "--clean Remove targets instead of building" ; |
| print.list-item "-a Rebuild everything" ; |
| print.list-item "-n Don't execute the commands, only print them" ; |
| print.list-item "-d+2 Show commands as they are executed" ; |
| print.list-item "-d0 Supress all informational messages" ; |
| print.list-item "-q Stop at first error" ; |
| print.list-item "--debug-configuration Diagnose configuration" ; |
| print.list-item "--debug-building Report which targets are built with what properties" ; |
| print.list-item "--debug-generator Diagnose generator search/execution" ; |
| print.list-end ; |
| |
| print.section "Further Help" |
| The following options can be used to obtain additional documentation. |
| ; |
| |
| print.list-start ; |
| print.list-item "--help-options Print more obscure command line options." ; |
| print.list-item "--help-internal Boost.Build implementation details." ; |
| print.list-item "--help-doc-options Implementation details doc formatting." ; |
| 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; |
| Output the used build commands to file '"x"'. ; |
| print.list-item -q; |
| Quit as soon as a build failure is encountered. Without this option |
| Boost.Jam will continue building as many targets as it can. |
| 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; |
| Any option not explicitly handled by Boost.Jam remains available to |
| build scripts using 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 |
| 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 all possible modules. We attempt to list all known |
| # modules together with 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" |
| 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 ; |
| } |
| } |
| } |
| } |
| |
| |
| # Generate documentation for a project. |
| # |
| local rule print-help-project ( |
| unused ? |
| : jamfile * # The project Jamfile. |
| ) |
| { |
| if $(jamfile<$(jamfile)>.docs) |
| { |
| # Print the docs. |
| print.section "Project-specific help" |
| Project has jamfile at $(jamfile) ; |
| |
| print.lines $(jamfile<$(jamfile)>.docs) "" ; |
| } |
| } |
| |
| |
| # Generate documentation for a config file. |
| # |
| local rule print-help-config ( |
| unused ? |
| : type # The type of configuration file user or site. |
| config-file # The configuration Jamfile. |
| ) |
| { |
| if $(jamfile<$(config-file)>.docs) |
| { |
| # Print the docs. |
| print.section "Configuration help" |
| Configuration file at $(config-file) ; |
| |
| print.lines $(jamfile<$(config-file)>.docs) "" ; |
| } |
| } |
| |
| |
| 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 rule 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. |
| : action * # Rule to call to output docs for the module. |
| ) |
| { |
| if $(.option.debug) { ECHO "HELP:" scanning module target '$(target)' ; } |
| local module-name = $(target:B) ; |
| local module-documented = ; |
| local comment-block = ; |
| local syntax-block = ; |
| # This is a hack because we can not 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 $(action[1]) in "print-help-project" "print-help-config" |
| && ! $(jamfile<$(target)>.docs) |
| { |
| # special module docs for the project jamfile. |
| jamfile<$(target)>.docs = $(comment-block) ; |
| } |
| else if ! $(module-documented) |
| { |
| # document the module. |
| set-module-doc $(module-name) : $(comment-block) ; |
| module-documented = true ; |
| } |
| } |
| if $(action) |
| { |
| $(action[1]) $(module-name) : $(action[2-]) ; |
| } |
| } |
| |
| |
| # Import scan-module to global scope, so that it is available during header |
| # scanning phase. |
| # |
| IMPORT $(__name__) : scan-module : : doc.scan-module ; |
| |
| |
| # Read in a file using the SHELL builtin and return the individual lines as |
| # would be done for header scanning. |
| # |
| local rule read-file ( |
| file # The file to read in. |
| ) |
| { |
| file = [ path.native [ path.root [ path.make $(file) ] [ path.pwd ] ] ] ; |
| if ! $(.file<$(file)>.lines) |
| { |
| local content ; |
| switch [ modules.peek : OS ] |
| { |
| case NT : |
| content = [ SHELL "TYPE \"$(file)\"" ] ; |
| |
| case * : |
| content = [ SHELL "cat \"$(file)\"" ] ; |
| } |
| local lines ; |
| local nl = " |
| " ; |
| local << = "([^$(nl)]*)[$(nl)](.*)" ; |
| local line+ = [ MATCH "$(<<)" : "$(content)" ] ; |
| while $(line+) |
| { |
| lines += $(line+[1]) ; |
| line+ = [ MATCH "$(<<)" : "$(line+[2])" ] ; |
| } |
| .file<$(file)>.lines = $(lines) ; |
| } |
| return $(.file<$(file)>.lines) ; |
| } |
| |
| |
| # 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. |
| ) |
| { |
| if $(help-output) = text |
| { |
| print.output $(help-output-file).txt plain ; |
| ALWAYS $(help-output-file).txt ; |
| DEPENDS all : $(help-output-file).txt ; |
| } |
| if $(help-output) = html |
| { |
| print.output $(help-output-file).html html ; |
| ALWAYS $(help-output-file).html ; |
| DEPENDS all : $(help-output-file).html ; |
| } |
| for local module-file in $(modules[1--2]) |
| { |
| scan-module $(module-file) : [ read-file $(module-file) ] ; |
| } |
| scan-module $(modules[-1]) : [ read-file $(modules[-1]) ] : $(action) ; |
| } |
