tools/boostbook/xsl/function.xsl
<?xml version="1.0" encoding="utf-8"?> <!-- Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com> Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:strip-space elements="requires effects postconditions returns throws complexity notes rationale purpose"/> <!-- When true, the stylesheet will emit compact definitions of functions when the function does not have any detailed description. --> <xsl:param name="boost.compact.function">1</xsl:param> <!-- The longest type length that is considered "short" for the layout of function return types. When the length of the result type and any storage specifiers is greater than this length, they will be placed on a separate line from the function name and parameters unless everything fits on a single line. --> <xsl:param name="boost.short.result.type">12</xsl:param> <!-- When true, the stylesheet will sort parameters of functions and templates alphabetically in detailed description. --> <xsl:param name="boost.sort.params">0</xsl:param> <!-- Display a function declaration --> <xsl:template name="function"> <xsl:param name="indentation"/> <xsl:param name="is-reference"/> <!-- Whether or not we should include parameter names in the output --> <xsl:param name="include-names" select="$is-reference"/> <!-- What type of link the function name should have. This shall be one of 'anchor' (the function output will be the target of links), 'link' (the function output will link to a definition), or 'none' (the function output will not be either a link or a link target) --> <xsl:param name="link-type"> <xsl:choose> <xsl:when test="$is-reference"> <xsl:text>anchor</xsl:text> </xsl:when> <xsl:otherwise> <xsl:text>link</xsl:text> </xsl:otherwise> </xsl:choose> </xsl:param> <!-- The id we should link to or anchor as --> <xsl:param name="link-to"> <xsl:call-template name="generate.id"/> </xsl:param> <!-- If we are printing a constructor --> <xsl:param name="constructor-for"/> <!-- If we are printing a destructor --> <xsl:param name="destructor-for"/> <!-- If we are printing a copy assignment operator --> <xsl:param name="copy-assign-for"/> <!-- The name of this function --> <xsl:param name="name" select="@name"/> <!-- True if this is the function's separate documentation --> <xsl:param name="standalone" select="false()"/> <!-- True if we should suppress the template header --> <xsl:param name="suppress-template" select="false()"/> <!-- Calculate the specifiers --> <xsl:variable name="specifiers"> <xsl:if test="@specifiers"> <xsl:value-of select="concat(@specifiers, ' ')"/> </xsl:if> </xsl:variable> <!-- Calculate the type --> <xsl:variable name="type"> <xsl:value-of select="$specifiers"/> <xsl:choose> <!-- Conversion operators have an empty type, because the return type is part of the name --> <xsl:when test="$name='conversion-operator'"/> <!-- Constructors and destructors have no return type --> <xsl:when test="$constructor-for or $destructor-for"/> <!-- Copy assignment operators return a reference to the class they are in, unless another type has been explicitly provided in the element. --> <xsl:when test="$copy-assign-for and not(type)"> <xsl:value-of select="concat($copy-assign-for, '& ')"/> </xsl:when> <xsl:otherwise> <xsl:apply-templates select="type" mode="annotation"/> <xsl:text> </xsl:text> </xsl:otherwise> </xsl:choose> </xsl:variable> <!-- Build the function name with return type --> <xsl:variable name="function-name"> <xsl:choose> <xsl:when test="$constructor-for"> <xsl:value-of select="$constructor-for"/> </xsl:when> <xsl:when test="$destructor-for"> <xsl:value-of select="concat('~',$destructor-for)"/> </xsl:when> <xsl:when test="$copy-assign-for"> <xsl:value-of select="'operator='"/> </xsl:when> <xsl:when test="$name='conversion-operator'"> <xsl:text>operator </xsl:text> <xsl:apply-templates select="type" mode="annotation"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="$name"/> </xsl:otherwise> </xsl:choose> </xsl:variable> <xsl:if test="not ($standalone) or (local-name(.)='signature' and (position() > 1)) or $suppress-template"> <xsl:text> </xsl:text> </xsl:if> <!-- Indent this declaration --> <xsl:call-template name="indent"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:call-template> <!-- Build the template header --> <xsl:variable name="template-length"> <xsl:choose> <xsl:when test="$suppress-template"> 0 </xsl:when> <xsl:otherwise> <xsl:call-template name="template.synopsis.length"/> </xsl:otherwise> </xsl:choose> </xsl:variable> <!-- Build a full parameter string (without line breaks) --> <xsl:variable name="param-string"> <xsl:text>(</xsl:text> <xsl:call-template name="function-parameters"> <xsl:with-param name="include-names" select="$include-names"/> <xsl:with-param name="wrap" select="false()"/> </xsl:call-template> <xsl:text>)</xsl:text> </xsl:variable> <!-- Build the text that follows the declarator--> <xsl:variable name="postdeclarator"> <xsl:if test="@cv and @cv != ''"> <xsl:text> </xsl:text> <xsl:value-of select="@cv"/> </xsl:if> </xsl:variable> <!-- Build the full declaration text --> <xsl:variable name="decl-string" select="concat($type, $function-name, $param-string, $postdeclarator)"/> <xsl:variable name="end-column" select="$template-length + string-length($decl-string) + $indentation"/> <xsl:choose> <!-- Check if we should put the template header on its own line to save horizontal space. --> <xsl:when test="($template-length > 0) and ($end-column > $max-columns)"> <!-- Emit template header on its own line --> <xsl:apply-templates select="template" mode="synopsis"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:apply-templates> <!-- Emit the rest of the function declaration (without the template header) indented two extra spaces. --> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="$indentation + 2"/> <xsl:with-param name="is-reference" select="$is-reference"/> <xsl:with-param name="include-names" select="$include-names"/> <xsl:with-param name="link-type" select="$link-type"/> <xsl:with-param name="link-to" select="$link-to"/> <xsl:with-param name="constructor-for" select="$constructor-for"/> <xsl:with-param name="destructor-for" select="$destructor-for"/> <xsl:with-param name="copy-assign-for" select="$copy-assign-for"/> <xsl:with-param name="name" select="$name"/> <xsl:with-param name="standalone" select="$standalone"/> <xsl:with-param name="suppress-template" select="true()"/> </xsl:call-template> </xsl:when> <!-- Check if we can put the entire declaration on a single line. --> <xsl:when test="not($end-column > $max-columns)"> <!-- Emit template header, if not suppressed --> <xsl:if test="not($suppress-template)"> <xsl:apply-templates select="template" mode="synopsis"> <xsl:with-param name="indentation" select="$indentation"/> <xsl:with-param name="wrap" select="false()"/> <xsl:with-param name="highlight" select="true()"/> </xsl:apply-templates> </xsl:if> <!-- Emit specifiers --> <xsl:call-template name="source-highlight"> <xsl:with-param name="text" select="$specifiers"/> </xsl:call-template> <!-- Emit type, if any --> <xsl:choose> <!-- Conversion operators have an empty type, because the return type is part of the name --> <xsl:when test="$name='conversion-operator'"/> <!-- Constructors and destructors have no return type --> <xsl:when test="$constructor-for or $destructor-for"/> <!-- Copy assignment operators return a reference to the class they are in, unless another type has been explicitly provided in the element. --> <xsl:when test="$copy-assign-for and not(type)"> <xsl:value-of select="concat($copy-assign-for, '& ')"/> </xsl:when> <xsl:otherwise> <xsl:apply-templates select="type" mode="highlight"/> <xsl:text> </xsl:text> </xsl:otherwise> </xsl:choose> <xsl:call-template name="link-or-anchor"> <xsl:with-param name="to" select="$link-to"/> <xsl:with-param name="text" select="$function-name"/> <xsl:with-param name="link-type" select="$link-type"/> <xsl:with-param name="highlight" select="true()"/> </xsl:call-template> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="'('"/> </xsl:call-template> <xsl:call-template name="function-parameters"> <xsl:with-param name="include-names" select="$include-names"/> <xsl:with-param name="indentation" select="$indentation + $template-length + string-length($type) + string-length($function-name) + 1"/> <xsl:with-param name="final" select="true()"/> </xsl:call-template> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="')'"/> </xsl:call-template> <xsl:call-template name="source-highlight"> <xsl:with-param name="text" select="$postdeclarator"/> </xsl:call-template> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="';'"/> </xsl:call-template> </xsl:when> <!-- This declaration will take multiple lines --> <xsl:otherwise> <!-- Emit specifiers --> <xsl:call-template name="source-highlight"> <xsl:with-param name="text" select="$specifiers"/> </xsl:call-template> <!-- Emit type, if any --> <xsl:choose> <!-- Conversion operators have an empty type, because the return type is part of the name --> <xsl:when test="$name='conversion-operator'"/> <!-- Constructors and destructors have no return type --> <xsl:when test="$constructor-for or $destructor-for"/> <!-- Copy assignment operators return a reference to the class they are in, unless another type has been explicitly provided in the element. --> <xsl:when test="$copy-assign-for and not(type)"> <xsl:value-of select="concat($copy-assign-for, '& ')"/> </xsl:when> <xsl:otherwise> <xsl:apply-templates select="type" mode="highlight"/> <xsl:text> </xsl:text> </xsl:otherwise> </xsl:choose> <xsl:if test="string-length($type) > $boost.short.result.type"> <xsl:text> </xsl:text> <xsl:call-template name="indent"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:call-template> </xsl:if> <!-- Determine how many columns the type and storage specifiers take on the same line as the function name. --> <xsl:variable name="type-length"> <xsl:choose> <xsl:when test="string-length($type) > $boost.short.result.type"> 0 </xsl:when> <xsl:otherwise> <xsl:value-of select="string-length($type)"/> </xsl:otherwise> </xsl:choose> </xsl:variable> <xsl:call-template name="link-or-anchor"> <xsl:with-param name="to" select="$link-to"/> <xsl:with-param name="text" select="$function-name"/> <xsl:with-param name="link-type" select="$link-type"/> <xsl:with-param name="highlight" select="true()"/> </xsl:call-template> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="'('"/> </xsl:call-template> <xsl:call-template name="function-parameters"> <xsl:with-param name="include-names" select="$include-names"/> <xsl:with-param name="indentation" select="$indentation + $type-length + string-length($function-name) + 1"/> <xsl:with-param name="final" select="true()"/> </xsl:call-template> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="')'"/> </xsl:call-template> <xsl:call-template name="source-highlight"> <xsl:with-param name="text" select="$postdeclarator"/> </xsl:call-template> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="';'"/> </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:template> <!-- Synopsis of function parameters, e.g., "(const T&, int x = 5)" --> <xsl:template name="function-parameters"> <!-- Indentation level of this parameter list --> <xsl:param name="indentation"/> <!-- True if we should include parameter names --> <xsl:param name="include-names" select="true()"/> <!-- True if we should wrap function parameters to the next line --> <xsl:param name="wrap" select="true()"/> <!-- True if we are printing the final output --> <xsl:param name="final" select="false()"/> <!-- Internal: The prefix to emit before a parameter --> <xsl:param name="prefix" select="''"/> <!-- Internal: The list of parameters --> <xsl:param name="parameters" select="parameter"/> <!-- Internal: The column we are on --> <xsl:param name="column" select="$indentation"/> <!-- Internal: Whether this is the first parameter on this line or not --> <xsl:param name="first-on-line" select="true()"/> <xsl:if test="$parameters"> <!-- Information for this parameter --> <xsl:variable name="parameter" select="$parameters[position()=1]"/> <xsl:variable name="pack"> <xsl:if test="$parameter/@pack=1"> <xsl:choose> <xsl:when test="$final"> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="'...'"/> </xsl:call-template> </xsl:when> <xsl:otherwise> <xsl:text>...</xsl:text> </xsl:otherwise> </xsl:choose> </xsl:if> </xsl:variable> <xsl:variable name="name"> <xsl:if test="$include-names and $parameter/@name != ''"> <xsl:text> </xsl:text><xsl:value-of select="$parameter/@name"/> </xsl:if> </xsl:variable> <xsl:variable name="type" select="string($parameter/paramtype)"/> <xsl:variable name="default"> <xsl:choose> <xsl:when test="$parameter/@default"> <xsl:choose> <xsl:when test="$final"> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="concat(' = ', $parameter/@default)"/> </xsl:call-template> </xsl:when> <xsl:otherwise> <xsl:text> = </xsl:text> <xsl:value-of select="$parameter/@default"/> </xsl:otherwise> </xsl:choose> </xsl:when> <xsl:when test="$parameter/default"> <xsl:choose> <xsl:when test="$final"> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="' = '"/> </xsl:call-template> <xsl:apply-templates select="$parameter/default/*|$parameter/default/text()" mode="annotation"> <xsl:with-param name="highlight" select="true()"/> </xsl:apply-templates> </xsl:when> <xsl:otherwise> <xsl:text> = </xsl:text> <xsl:value-of select="string($parameter/default)"/> </xsl:otherwise> </xsl:choose> </xsl:when> </xsl:choose> </xsl:variable> <xsl:variable name="text" select="concat($type, $pack, $name, $default)"/> <xsl:variable name="end-column" select="$column + string-length($prefix) + string-length($text)"/> <xsl:choose> <!-- Parameter goes on this line --> <xsl:when test="$first-on-line or ($end-column < $max-columns) or not($wrap)"> <xsl:choose> <xsl:when test="$final"> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="$prefix"/> </xsl:call-template> <xsl:apply-templates select="$parameter/paramtype/*|$parameter/paramtype/text()" mode="annotation"> <xsl:with-param name="highlight" select="true()"/> </xsl:apply-templates> <xsl:copy-of select="$pack"/> <xsl:value-of select="$name"/> <xsl:copy-of select="$default"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="concat($prefix, $text)"/> </xsl:otherwise> </xsl:choose> <xsl:call-template name="function-parameters"> <xsl:with-param name="indentation" select="$indentation"/> <xsl:with-param name="include-names" select="$include-names"/> <xsl:with-param name="wrap" select="$wrap"/> <xsl:with-param name="final" select="$final"/> <xsl:with-param name="parameters" select="$parameters[position()!=1]"/> <xsl:with-param name="prefix" select="', '"/> <xsl:with-param name="column" select="$end-column"/> <xsl:with-param name="first-on-line" select="false()"/> </xsl:call-template> </xsl:when> <!-- Parameter goes on next line --> <xsl:otherwise> <!-- The comma goes on this line --> <xsl:choose> <xsl:when test="$final"> <xsl:call-template name="highlight-text"> <xsl:with-param name="text" select="$prefix"/> </xsl:call-template> </xsl:when> <xsl:otherwise> <xsl:value-of select="$prefix"/> </xsl:otherwise> </xsl:choose> <xsl:text> </xsl:text> <!-- Indent and print the parameter --> <xsl:call-template name="indent"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:call-template> <xsl:choose> <xsl:when test="$final"> <xsl:apply-templates select="$parameter/paramtype/*|$parameter/paramtype/text()" mode="annotation"> <xsl:with-param name="highlight" select="true()"/> </xsl:apply-templates> <xsl:copy-of select="$pack"/> <xsl:value-of select="$name"/> <xsl:copy-of select="$default"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="concat($prefix, $text)"/> </xsl:otherwise> </xsl:choose> <!-- Emit next parameter --> <xsl:call-template name="function-parameters"> <xsl:with-param name="indentation" select="$indentation"/> <xsl:with-param name="include-names" select="$include-names"/> <xsl:with-param name="wrap" select="$wrap"/> <xsl:with-param name="final" select="$final"/> <xsl:with-param name="parameters" select="$parameters[position()!=1]"/> <xsl:with-param name="prefix" select="', '"/> <xsl:with-param name="column" select="1 + string-length($text) + $indentation"/> <xsl:with-param name="first-on-line" select="false()"/> </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:if> </xsl:template> <!-- Function synopsis --> <xsl:template match="function|method" mode="synopsis"> <xsl:param name="indentation"/> <!-- True if we should compact this function --> <xsl:variable name="compact" select="not (para|description|requires|effects|postconditions|returns| throws|complexity|notes|rationale) and ($boost.compact.function='1') and not (local-name(.)='method')"/> <xsl:choose> <xsl:when test="$compact"> <xsl:if test="purpose"> <!-- Compact display outputs the purpose as a comment (if there is one) and the entire function declaration. --> <xsl:text> </xsl:text> <xsl:call-template name="indent"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:call-template> <xsl:call-template name="highlight-comment"> <xsl:with-param name="text"> <xsl:text>// </xsl:text> <xsl:apply-templates select="purpose/*|purpose/text()" mode="purpose"/> </xsl:with-param> </xsl:call-template> </xsl:if> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="$indentation"/> <xsl:with-param name="is-reference" select="true()"/> </xsl:call-template> </xsl:when> <xsl:otherwise> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="$indentation"/> <xsl:with-param name="is-reference" select="false()"/> </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:template> <xsl:template match="overloaded-function|overloaded-method" mode="synopsis"> <xsl:param name="indentation"/> <xsl:variable name="name" select="@name"/> <!-- True if we should compact this function --> <xsl:variable name="compact" select="not (para|description|requires|effects|postconditions|returns| throws|complexity|notes|rationale) and ($boost.compact.function='1') and not (local-name(.)='overloaded-method')"/> <xsl:choose> <xsl:when test="$compact"> <xsl:if test="purpose"> <!-- Compact display outputs the purpose as a comment (if there is one) and the entire function declaration. --> <xsl:text> </xsl:text> <xsl:call-template name="indent"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:call-template> <xsl:call-template name="highlight-comment"> <xsl:with-param name="text"> <xsl:text>// </xsl:text> <xsl:apply-templates select="purpose" mode="annotation"/> </xsl:with-param> </xsl:call-template> </xsl:if> <xsl:for-each select="signature"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="$indentation"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="name" select="$name"/> </xsl:call-template> </xsl:for-each> </xsl:when> <xsl:when test="local-name(..)='namespace'"> <xsl:variable name="link-to"> <xsl:call-template name="generate.id"/> </xsl:variable> <xsl:for-each select="signature"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="$indentation"/> <xsl:with-param name="is-reference" select="false()"/> <xsl:with-param name="name" select="$name"/> <xsl:with-param name="link-to" select="$link-to"/> </xsl:call-template> </xsl:for-each> </xsl:when> <xsl:otherwise> <xsl:for-each select="signature"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="$indentation"/> <xsl:with-param name="is-reference" select="false()"/> <xsl:with-param name="name" select="$name"/> </xsl:call-template> </xsl:for-each> </xsl:otherwise> </xsl:choose> </xsl:template> <!-- Group free functions together under a category name (header synopsis)--> <xsl:template match="free-function-group" mode="header-synopsis"> <xsl:param name="class"/> <xsl:param name="indentation"/> <xsl:apply-templates select="function|overloaded-function" mode="synopsis"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:apply-templates> </xsl:template> <!-- Constructors, destructor, and assignment operators --> <xsl:template name="construct-copy-destruct-synopsis"> <xsl:param name="indentation"/> <xsl:if test="constructor|copy-assignment|destructor"> <xsl:if test="typedef|static-constant"> <xsl:text> </xsl:text> </xsl:if> <xsl:text> </xsl:text> <xsl:call-template name="indent"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:call-template> <xsl:call-template name="highlight-comment"> <xsl:with-param name="text"> <xsl:text>// </xsl:text> <xsl:call-template name="internal-link"> <xsl:with-param name="to"> <xsl:call-template name="generate.id"/> <xsl:text>construct-copy-destruct</xsl:text> </xsl:with-param> <xsl:with-param name="text" select="'construct/copy/destruct'"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> <xsl:apply-templates select="constructor" mode="synopsis"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:apply-templates> <xsl:apply-templates select="copy-assignment" mode="synopsis"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:apply-templates> <xsl:apply-templates select="destructor" mode="synopsis"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:apply-templates> </xsl:if> </xsl:template> <xsl:template name="construct-copy-destruct-reference"> <xsl:if test="constructor|copy-assignment|destructor"> <xsl:call-template name="member-documentation"> <xsl:with-param name="name"> <xsl:call-template name="anchor"> <xsl:with-param name="to"> <xsl:call-template name="generate.id"/> <xsl:text>construct-copy-destruct</xsl:text> </xsl:with-param> <xsl:with-param name="text" select="''"/> </xsl:call-template> <xsl:call-template name="monospaced"> <xsl:with-param name="text"> <xsl:call-template name="object-name"/> </xsl:with-param> </xsl:call-template> <xsl:text> </xsl:text> <xsl:call-template name="access-name"/> <xsl:text> construct/copy/destruct</xsl:text> </xsl:with-param> <xsl:with-param name="text"> <orderedlist> <xsl:apply-templates select="constructor" mode="reference"/> <xsl:apply-templates select="copy-assignment" mode="reference"/> <xsl:apply-templates select="destructor" mode="reference"/> </orderedlist> </xsl:with-param> </xsl:call-template> </xsl:if> </xsl:template> <xsl:template match="constructor" mode="reference"> <xsl:call-template name="function.documentation"> <xsl:with-param name="text"> <para> <xsl:call-template name="preformatted"> <xsl:with-param name="text"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="0"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="constructor-for"> <xsl:call-template name="object-name"/> </xsl:with-param> <xsl:with-param name="standalone" select="true()"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> </para> <xsl:call-template name="function-requirements"/> </xsl:with-param> </xsl:call-template> </xsl:template> <xsl:template match="copy-assignment" mode="reference"> <xsl:call-template name="function.documentation"> <xsl:with-param name="text"> <para> <xsl:call-template name="preformatted"> <xsl:with-param name="text"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="0"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="copy-assign-for"> <xsl:call-template name="object-name"/> </xsl:with-param> <xsl:with-param name="standalone" select="true()"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> </para> <xsl:call-template name="function-requirements"/> </xsl:with-param> </xsl:call-template> </xsl:template> <xsl:template match="destructor" mode="reference"> <xsl:call-template name="function.documentation"> <xsl:with-param name="text"> <para> <xsl:call-template name="preformatted"> <xsl:with-param name="text"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="0"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="destructor-for"> <xsl:call-template name="object-name"/> </xsl:with-param> <xsl:with-param name="standalone" select="true()"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> </para> <xsl:call-template name="function-requirements"/> </xsl:with-param> </xsl:call-template> </xsl:template> <!-- Templates for functions --> <xsl:template name="function.documentation"> <xsl:param name="text"/> <xsl:choose> <xsl:when test="count(ancestor::free-function-group) > 0 or count(ancestor::method-group) > 0 or local-name(.)='constructor' or local-name(.)='copy-assignment' or local-name(.)='destructor'"> <listitem><xsl:copy-of select="$text"/></listitem> </xsl:when> <xsl:otherwise> <xsl:copy-of select="$text"/> </xsl:otherwise> </xsl:choose> </xsl:template> <!-- Semantic descriptions of functions --> <xsl:template name="function-requirements"> <xsl:param name="namespace-reference" select="false()"/> <xsl:if test="$namespace-reference=false()"> <xsl:apply-templates select="purpose/*|purpose/text()"/> </xsl:if> <xsl:apply-templates select="description/*"/> <xsl:if test="parameter/description|signature/parameter/description| template/template-type-parameter/purpose| template/template-nontype-parameter/purpose| requires|effects|postconditions|returns|throws|complexity| notes|rationale"> <variablelist spacing="compact"> <xsl:processing-instruction name="dbhtml"> list-presentation="table" </xsl:processing-instruction> <!-- Document parameters --> <xsl:if test="parameter/description|signature/parameter/description"> <varlistentry> <term>Parameters:</term> <listitem> <variablelist spacing="compact"> <xsl:processing-instruction name="dbhtml"> list-presentation="table" </xsl:processing-instruction> <xsl:for-each select="parameter|signature/parameter"> <xsl:sort select="attribute::name[$boost.sort.params!=0]"/> <xsl:if test="description"> <varlistentry> <term> <xsl:call-template name="monospaced"> <xsl:with-param name="text" select="@name"/> </xsl:call-template> </term> <listitem> <xsl:apply-templates select="description/*"/> </listitem> </varlistentry> </xsl:if> </xsl:for-each> </variablelist> </listitem> </varlistentry> </xsl:if> <!-- Document template parameters --> <xsl:if test="template/template-type-parameter/purpose| template/template-nontype-parameter/purpose"> <varlistentry> <term>Template Parameters:</term> <listitem> <variablelist spacing="compact"> <xsl:processing-instruction name="dbhtml"> list-presentation="table" </xsl:processing-instruction> <xsl:for-each select="template/template-type-parameter| template/template-nontype-parameter"> <xsl:sort select="attribute::name[$boost.sort.params!=0]"/> <xsl:if test="purpose"> <varlistentry> <term> <xsl:call-template name="monospaced"> <xsl:with-param name="text" select="@name"/> </xsl:call-template> </term> <listitem> <xsl:apply-templates select="purpose/*"/> </listitem> </varlistentry> </xsl:if> </xsl:for-each> </variablelist> </listitem> </varlistentry> </xsl:if> <!-- Document rest of function's contract --> <xsl:for-each select="requires|effects|postconditions|returns|throws|complexity| notes|rationale"> <varlistentry> <term><xsl:call-template name="function.requirement.name"/>:</term> <listitem> <xsl:apply-templates select="./*|./text()" mode="annotation"/> </listitem> </varlistentry> </xsl:for-each> </variablelist> </xsl:if> <xsl:if test="para"> <xsl:message> <xsl:text>Warning: Use of 'para' elements in a function is deprecated. </xsl:text> <xsl:text> Wrap them in a 'description' element.</xsl:text> </xsl:message> <xsl:call-template name="print.warning.context"/> <xsl:apply-templates select="para"/> </xsl:if> </xsl:template> <xsl:template name="function.requirement.name"> <xsl:param name="node" select="."/> <xsl:choose> <xsl:when test="local-name($node)='requires'">Requires</xsl:when> <xsl:when test="local-name($node)='effects'">Effects</xsl:when> <xsl:when test="local-name($node)='postconditions'"> <xsl:text>Postconditions</xsl:text> </xsl:when> <xsl:when test="local-name($node)='returns'">Returns</xsl:when> <xsl:when test="local-name($node)='throws'">Throws</xsl:when> <xsl:when test="local-name($node)='complexity'">Complexity</xsl:when> <xsl:when test="local-name($node)='notes'">Notes</xsl:when> <xsl:when test="local-name($node)='rationale'">Rationale</xsl:when> <xsl:otherwise> <xsl:message> <xsl:text>Error: unhandled node type `</xsl:text> <xsl:value-of select="local-name($node)"/> <xsl:text>' in template function.requirement.name.</xsl:text> </xsl:message> </xsl:otherwise> </xsl:choose> </xsl:template> <!-- Function reference --> <xsl:template match="function|method" mode="reference"> <!-- True if we should compact this function --> <xsl:variable name="compact" select="not (para|description|requires|effects|postconditions|returns| throws|complexity|notes|rationale) and ($boost.compact.function='1') and not (local-name(.)='method')"/> <xsl:if test="not ($compact)"> <xsl:call-template name="function.documentation"> <xsl:with-param name="text"> <para> <xsl:call-template name="preformatted"> <xsl:with-param name="text"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="0"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="link-type" select="'anchor'"/> <xsl:with-param name="standalone" select="true()"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> </para> <xsl:call-template name="function-requirements"/> </xsl:with-param> </xsl:call-template> </xsl:if> </xsl:template> <!-- Reference for functions at namespace level --> <xsl:template match="function" mode="namespace-reference"> <!-- True if we should compact this function --> <xsl:variable name="compact" select="not (para|description|requires|effects|postconditions|returns| throws|complexity|notes|rationale) and ($boost.compact.function='1')"/> <xsl:if test="not ($compact)"> <xsl:call-template name="reference-documentation"> <xsl:with-param name="name"> <xsl:text>Function </xsl:text> <xsl:if test="template"> <xsl:text>template </xsl:text> </xsl:if> <xsl:call-template name="monospaced"> <xsl:with-param name="text" select="@name"/> </xsl:call-template> </xsl:with-param> <xsl:with-param name="refname"> <xsl:call-template name="fully-qualified-name"> <xsl:with-param name="node" select="."/> </xsl:call-template> </xsl:with-param> <xsl:with-param name="purpose" select="purpose/*|purpose/text()"/> <xsl:with-param name="anchor"> <xsl:call-template name="generate.id"/> </xsl:with-param> <xsl:with-param name="synopsis"> <xsl:call-template name="header-link"/> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="0"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="link-type" select="'none'"/> </xsl:call-template> </xsl:with-param> <xsl:with-param name="text"> <xsl:call-template name="function-requirements"> <xsl:with-param name="namespace-reference" select="true()"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> </xsl:if> </xsl:template> <xsl:template match="overloaded-function" mode="reference"> <xsl:variable name="name" select="@name"/> <!-- True if we should compact this function --> <xsl:variable name="compact" select="not (para|description|requires|effects|postconditions|returns| throws|complexity|notes|rationale) and ($boost.compact.function='1')"/> <xsl:if test="not ($compact)"> <xsl:call-template name="function.documentation"> <xsl:with-param name="text"> <para> <xsl:attribute name="id"> <xsl:call-template name="generate.id"/> </xsl:attribute> <xsl:call-template name="preformatted"> <xsl:with-param name="text"> <xsl:for-each select="signature"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="0"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="name" select="$name"/> <xsl:with-param name="standalone" select="true()"/> </xsl:call-template> </xsl:for-each> </xsl:with-param> </xsl:call-template> </para> <xsl:call-template name="function-requirements"/> </xsl:with-param> </xsl:call-template> </xsl:if> </xsl:template> <xsl:template match="overloaded-function" mode="namespace-reference"> <!-- True if we should compact this function --> <xsl:variable name="compact" select="not (para|description|requires|effects|postconditions|returns| throws|complexity|notes|rationale) and ($boost.compact.function='1')"/> <xsl:variable name="name" select="@name"/> <xsl:if test="not ($compact)"> <xsl:call-template name="reference-documentation"> <xsl:with-param name="name"> <xsl:text>Function </xsl:text> <xsl:if test="template"> <xsl:text>template </xsl:text> </xsl:if> <xsl:call-template name="monospaced"> <xsl:with-param name="text" select="@name"/> </xsl:call-template> </xsl:with-param> <xsl:with-param name="refname"> <xsl:call-template name="fully-qualified-name"> <xsl:with-param name="node" select="."/> </xsl:call-template> </xsl:with-param> <xsl:with-param name="purpose" select="purpose/*|purpose/text()"/> <xsl:with-param name="anchor"> <xsl:call-template name="generate.id"/> </xsl:with-param> <xsl:with-param name="synopsis"> <xsl:call-template name="header-link"/> <xsl:for-each select="signature"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="0"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="link-type" select="'none'"/> <xsl:with-param name="name" select="$name"/> </xsl:call-template> </xsl:for-each> </xsl:with-param> <xsl:with-param name="text"> <xsl:call-template name="function-requirements"> <xsl:with-param name="namespace-reference" select="true()"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> </xsl:if> </xsl:template> <xsl:template match="overloaded-method" mode="reference"> <xsl:variable name="name" select="@name"/> <xsl:call-template name="function.documentation"> <xsl:with-param name="text"> <para> <xsl:call-template name="preformatted"> <xsl:with-param name="text"> <xsl:call-template name="anchor"> <xsl:with-param name="to"> <xsl:call-template name="generate.id"/> </xsl:with-param> </xsl:call-template> <xsl:for-each select="signature"> <xsl:call-template name="function"> <xsl:with-param name="indentation" select="0"/> <xsl:with-param name="is-reference" select="true()"/> <xsl:with-param name="name" select="$name"/> <xsl:with-param name="standalone" select="true()"/> </xsl:call-template> </xsl:for-each> </xsl:with-param> </xsl:call-template> </para> <xsl:call-template name="function-requirements"/> </xsl:with-param> </xsl:call-template> </xsl:template> <!-- Group member functions together under a category name (synopsis)--> <xsl:template match="method-group" mode="synopsis"> <xsl:param name="indentation"/> <xsl:if test="count(child::*) > 0"> <xsl:text> </xsl:text> <xsl:text> </xsl:text> <xsl:call-template name="indent"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:call-template> <xsl:call-template name="highlight-comment"> <xsl:with-param name="text"> <xsl:text>// </xsl:text> <xsl:call-template name="internal-link"> <xsl:with-param name="to"> <xsl:call-template name="generate.id"/> </xsl:with-param> <xsl:with-param name="text" select="string(@name)"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> <xsl:apply-templates select="constructor|copy-assignment|destructor|method|overloaded-method" mode="synopsis"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:apply-templates> </xsl:if> </xsl:template> <!-- Group member functions together under a category name (reference)--> <xsl:template match="method-group" mode="reference"> <xsl:if test="count(child::*) > 0"> <xsl:call-template name="member-documentation"> <xsl:with-param name="name"> <xsl:call-template name="anchor"> <xsl:with-param name="to"> <xsl:call-template name="generate.id"/> </xsl:with-param> <xsl:with-param name="text" select="''"/> </xsl:call-template> <xsl:call-template name="monospaced"> <xsl:with-param name="text"> <xsl:call-template name="object-name"/> </xsl:with-param> </xsl:call-template> <xsl:text> </xsl:text> <xsl:value-of select="@name"/> </xsl:with-param> <xsl:with-param name="text"> <orderedlist> <xsl:apply-templates select="constructor|copy-assignment|destructor|method|overloaded-method" mode="reference"/> </orderedlist> </xsl:with-param> </xsl:call-template> </xsl:if> </xsl:template> <!-- Group free functions together under a category name (synopsis)--> <xsl:template match="free-function-group" mode="synopsis"> <xsl:param name="class"/> <xsl:param name="indentation"/> <xsl:text> </xsl:text> <xsl:text> </xsl:text> <xsl:call-template name="indent"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:call-template> <xsl:call-template name="highlight-comment"> <xsl:with-param name="text"> <xsl:text>// </xsl:text> <xsl:call-template name="internal-link"> <xsl:with-param name="to"> <xsl:call-template name="generate.id"/> </xsl:with-param> <xsl:with-param name="text" select="string(@name)"/> </xsl:call-template> </xsl:with-param> </xsl:call-template> <xsl:apply-templates select="function|overloaded-function" mode="synopsis"> <xsl:with-param name="indentation" select="$indentation"/> </xsl:apply-templates> </xsl:template> <!-- Group free functions together under a category name (reference)--> <xsl:template match="free-function-group" mode="reference"> <xsl:param name="class"/> <xsl:call-template name="member-documentation"> <xsl:with-param name="name"> <xsl:call-template name="anchor"> <xsl:with-param name="to"> <xsl:call-template name="generate.id"/> </xsl:with-param> <xsl:with-param name="text" select="''"/> </xsl:call-template> <xsl:call-template name="monospaced"> <xsl:with-param name="text" select="$class"/> </xsl:call-template> <xsl:value-of select="concat(' ',@name)"/> </xsl:with-param> <xsl:with-param name="text"> <orderedlist> <xsl:apply-templates select="function|overloaded-function" mode="reference"/> </orderedlist> </xsl:with-param> </xsl:call-template> </xsl:template> </xsl:stylesheet>