1<?xml version="1.0" encoding="utf-8"?> 2<!-- 3 Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com> 4 5 Distributed under the Boost Software License, Version 1.0. 6 (See accompanying file LICENSE_1_0.txt or copy at 7 http://www.boost.org/LICENSE_1_0.txt) 8 --> 9<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 10 version="1.0"> 11 12 <xsl:strip-space elements="requires effects postconditions returns throws 13 complexity notes rationale purpose"/> 14 15 <!-- When true, the stylesheet will emit compact definitions of 16 functions when the function does not have any detailed 17 description. --> 18 <xsl:param name="boost.compact.function">1</xsl:param> 19 20 <!-- The longest type length that is considered "short" for the 21 layout of function return types. When the length of the result type 22 and any storage specifiers is greater than this length, they will be 23 placed on a separate line from the function name and parameters 24 unless everything fits on a single line. --> 25 <xsl:param name="boost.short.result.type">12</xsl:param> 26 27 <!-- Display a function declaration --> 28 <xsl:template name="function"> 29 <xsl:param name="indentation"/> 30 <xsl:param name="is-reference"/> 31 32 <!-- Whether or not we should include parameter names in the output --> 33 <xsl:param name="include-names" select="$is-reference"/> 34 35 <!-- What type of link the function name should have. This shall 36 be one of 'anchor' (the function output will be the target of 37 links), 'link' (the function output will link to a definition), or 38 'none' (the function output will not be either a link or a link 39 target) --> 40 <xsl:param name="link-type"> 41 <xsl:choose> 42 <xsl:when test="$is-reference"> 43 <xsl:text>anchor</xsl:text> 44 </xsl:when> 45 <xsl:otherwise> 46 <xsl:text>link</xsl:text> 47 </xsl:otherwise> 48 </xsl:choose> 49 </xsl:param> 50 51 <!-- The id we should link to or anchor as --> 52 <xsl:param name="link-to"> 53 <xsl:call-template name="generate.id"/> 54 </xsl:param> 55 56 <!-- If we are printing a constructor --> 57 <xsl:param name="constructor-for"/> 58 59 <!-- If we are printing a destructor --> 60 <xsl:param name="destructor-for"/> 61 62 <!-- If we are printing a copy assignment operator --> 63 <xsl:param name="copy-assign-for"/> 64 65 <!-- The name of this function --> 66 <xsl:param name="name" select="@name"/> 67 68 <!-- True if this is the function's separate documentation --> 69 <xsl:param name="standalone" select="false()"/> 70 71 <!-- True if we should suppress the template header --> 72 <xsl:param name="suppress-template" select="false()"/> 73 74 <!-- Calculate the specifiers --> 75 <xsl:variable name="specifiers"> 76 <xsl:if test="@specifiers"> 77 <xsl:value-of select="concat(@specifiers, ' ')"/> 78 </xsl:if> 79 </xsl:variable> 80 81 <!-- Calculate the type --> 82 <xsl:variable name="type"> 83 <xsl:value-of select="$specifiers"/> 84 85 <xsl:choose> 86 <!-- Conversion operators have an empty type, because the return 87 type is part of the name --> 88 <xsl:when test="$name='conversion-operator'"/> 89 90 <!-- Constructors and destructors have no return type --> 91 <xsl:when test="$constructor-for or $destructor-for"/> 92 93 <!-- Copy assignment operators return a reference to the class 94 they are in, unless another type has been explicitly 95 provided in the element. --> 96 <xsl:when test="$copy-assign-for and not(type)"> 97 <xsl:value-of select="concat($copy-assign-for, '& ')"/> 98 </xsl:when> 99 100 <xsl:otherwise> 101 <xsl:apply-templates select="type" mode="annotation"/> 102 <xsl:text> </xsl:text> 103 </xsl:otherwise> 104 </xsl:choose> 105 </xsl:variable> 106 107 <!-- Build the function name with return type --> 108 <xsl:variable name="function-name"> 109 <xsl:choose> 110 <xsl:when test="$constructor-for"> 111 <xsl:value-of select="$constructor-for"/> 112 </xsl:when> 113 <xsl:when test="$destructor-for"> 114 <xsl:value-of select="concat('~',$destructor-for)"/> 115 </xsl:when> 116 <xsl:when test="$copy-assign-for"> 117 <xsl:value-of select="'operator='"/> 118 </xsl:when> 119 <xsl:when test="$name='conversion-operator'"> 120 <xsl:text>operator </xsl:text> 121 <xsl:apply-templates select="type" mode="annotation"/> 122 </xsl:when> 123 <xsl:otherwise> 124 <xsl:value-of select="$name"/> 125 </xsl:otherwise> 126 </xsl:choose> 127 </xsl:variable> 128 129 <xsl:if test="not ($standalone) or 130 (local-name(.)='signature' and (position() > 1)) 131 or $suppress-template"> 132 <xsl:text> </xsl:text> 133 </xsl:if> 134 135 <!-- Indent this declaration --> 136 <xsl:call-template name="indent"> 137 <xsl:with-param name="indentation" select="$indentation"/> 138 </xsl:call-template> 139 140 <!-- Build the template header --> 141 <xsl:variable name="template-length"> 142 <xsl:choose> 143 <xsl:when test="$suppress-template"> 144 0 145 </xsl:when> 146 <xsl:otherwise> 147 <xsl:call-template name="template.synopsis.length"/> 148 </xsl:otherwise> 149 </xsl:choose> 150 </xsl:variable> 151 152 <!-- Build a full parameter string (without line breaks) --> 153 <xsl:variable name="param-string"> 154 <xsl:text>(</xsl:text> 155 <xsl:call-template name="function-parameters"> 156 <xsl:with-param name="include-names" select="$include-names"/> 157 <xsl:with-param name="wrap" select="false()"/> 158 </xsl:call-template> 159 <xsl:text>)</xsl:text> 160 </xsl:variable> 161 162 <!-- Build the text that follows the declarator--> 163 <xsl:variable name="postdeclarator"> 164 <xsl:if test="@cv and @cv != ''"> 165 <xsl:text> </xsl:text> 166 <xsl:value-of select="@cv"/> 167 </xsl:if> 168 </xsl:variable> 169 170 <!-- Build the full declaration text --> 171 <xsl:variable name="decl-string" 172 select="concat($type, $function-name, $param-string, $postdeclarator)"/> 173 <xsl:variable name="end-column" 174 select="$template-length + string-length($decl-string) + $indentation"/> 175 176 <xsl:choose> 177 <!-- Check if we should put the template header on its own line to 178 save horizontal space. --> 179 <xsl:when test="($template-length > 0) and 180 ($end-column > $max-columns)"> 181 <!-- Emit template header on its own line --> 182 <xsl:apply-templates select="template" mode="synopsis"> 183 <xsl:with-param name="indentation" select="$indentation"/> 184 </xsl:apply-templates> 185 186 <!-- Emit the rest of the function declaration (without the 187 template header) indented two extra spaces. --> 188 <xsl:call-template name="function"> 189 <xsl:with-param name="indentation" select="$indentation + 2"/> 190 <xsl:with-param name="is-reference" select="$is-reference"/> 191 <xsl:with-param name="include-names" select="$include-names"/> 192 <xsl:with-param name="link-type" select="$link-type"/> 193 <xsl:with-param name="link-to" select="$link-to"/> 194 <xsl:with-param name="constructor-for" select="$constructor-for"/> 195 <xsl:with-param name="destructor-for" select="$destructor-for"/> 196 <xsl:with-param name="copy-assign-for" select="$copy-assign-for"/> 197 <xsl:with-param name="name" select="$name"/> 198 <xsl:with-param name="standalone" select="$standalone"/> 199 <xsl:with-param name="suppress-template" select="true()"/> 200 </xsl:call-template> 201 </xsl:when> 202 203 <!-- Check if we can put the entire declaration on a single 204 line. --> 205 <xsl:when test="not($end-column > $max-columns)"> 206 <!-- Emit template header, if not suppressed --> 207 <xsl:if test="not($suppress-template)"> 208 <xsl:apply-templates select="template" mode="synopsis"> 209 <xsl:with-param name="indentation" select="$indentation"/> 210 <xsl:with-param name="wrap" select="false()"/> 211 <xsl:with-param name="highlight" select="true()"/> 212 </xsl:apply-templates> 213 </xsl:if> 214 215 <!-- Emit specifiers --> 216 <xsl:call-template name="source-highlight"> 217 <xsl:with-param name="text" select="$specifiers"/> 218 </xsl:call-template> 219 220 <!-- Emit type, if any --> 221 <xsl:choose> 222 <!-- Conversion operators have an empty type, because the return 223 type is part of the name --> 224 <xsl:when test="$name='conversion-operator'"/> 225 226 <!-- Constructors and destructors have no return type --> 227 <xsl:when test="$constructor-for or $destructor-for"/> 228 229 <!-- Copy assignment operators return a reference to the class 230 they are in, unless another type has been explicitly 231 provided in the element. --> 232 <xsl:when test="$copy-assign-for and not(type)"> 233 <xsl:value-of select="concat($copy-assign-for, '& ')"/> 234 </xsl:when> 235 236 <xsl:otherwise> 237 <xsl:apply-templates select="type" mode="highlight"/> 238 <xsl:text> </xsl:text> 239 </xsl:otherwise> 240 </xsl:choose> 241 242 <xsl:call-template name="link-or-anchor"> 243 <xsl:with-param name="to" select="$link-to"/> 244 <xsl:with-param name="text" select="$function-name"/> 245 <xsl:with-param name="link-type" select="$link-type"/> 246 <xsl:with-param name="highlight" select="true()"/> 247 </xsl:call-template> 248 249 <xsl:call-template name="highlight-text"> 250 <xsl:with-param name="text" select="'('"/> 251 </xsl:call-template> 252 <xsl:call-template name="function-parameters"> 253 <xsl:with-param name="include-names" select="$include-names"/> 254 <xsl:with-param name="indentation" 255 select="$indentation + $template-length + string-length($type) 256 + string-length($function-name) + 1"/> 257 <xsl:with-param name="final" select="true()"/> 258 </xsl:call-template> 259 <xsl:call-template name="highlight-text"> 260 <xsl:with-param name="text" select="')'"/> 261 </xsl:call-template> 262 263 <xsl:call-template name="source-highlight"> 264 <xsl:with-param name="text" select="$postdeclarator"/> 265 </xsl:call-template> 266 <xsl:call-template name="highlight-text"> 267 <xsl:with-param name="text" select="';'"/> 268 </xsl:call-template> 269 </xsl:when> 270 271 <!-- This declaration will take multiple lines --> 272 <xsl:otherwise> 273 <!-- Emit specifiers --> 274 <xsl:call-template name="source-highlight"> 275 <xsl:with-param name="text" select="$specifiers"/> 276 </xsl:call-template> 277 278 <!-- Emit type, if any --> 279 <xsl:choose> 280 <!-- Conversion operators have an empty type, because the return 281 type is part of the name --> 282 <xsl:when test="$name='conversion-operator'"/> 283 284 <!-- Constructors and destructors have no return type --> 285 <xsl:when test="$constructor-for or $destructor-for"/> 286 287 <!-- Copy assignment operators return a reference to the class 288 they are in, unless another type has been explicitly 289 provided in the element. --> 290 <xsl:when test="$copy-assign-for and not(type)"> 291 <xsl:value-of select="concat($copy-assign-for, '& ')"/> 292 </xsl:when> 293 294 <xsl:otherwise> 295 <xsl:apply-templates select="type" mode="highlight"/> 296 <xsl:text> </xsl:text> 297 </xsl:otherwise> 298 </xsl:choose> 299 300 <xsl:if test="string-length($type) > $boost.short.result.type"> 301 <xsl:text> </xsl:text> 302 <xsl:call-template name="indent"> 303 <xsl:with-param name="indentation" select="$indentation"/> 304 </xsl:call-template> 305 </xsl:if> 306 307 <!-- Determine how many columns the type and storage 308 specifiers take on the same line as the function name. --> 309 <xsl:variable name="type-length"> 310 <xsl:choose> 311 <xsl:when test="string-length($type) > $boost.short.result.type"> 312 0 313 </xsl:when> 314 <xsl:otherwise> 315 <xsl:value-of select="string-length($type)"/> 316 </xsl:otherwise> 317 </xsl:choose> 318 </xsl:variable> 319 320 <xsl:call-template name="link-or-anchor"> 321 <xsl:with-param name="to" select="$link-to"/> 322 <xsl:with-param name="text" select="$function-name"/> 323 <xsl:with-param name="link-type" select="$link-type"/> 324 <xsl:with-param name="highlight" select="true()"/> 325 </xsl:call-template> 326 <xsl:call-template name="highlight-text"> 327 <xsl:with-param name="text" select="'('"/> 328 </xsl:call-template> 329 <xsl:call-template name="function-parameters"> 330 <xsl:with-param name="include-names" select="$include-names"/> 331 <xsl:with-param name="indentation" 332 select="$indentation + $type-length 333 + string-length($function-name) + 1"/> 334 <xsl:with-param name="final" select="true()"/> 335 </xsl:call-template> 336 <xsl:call-template name="highlight-text"> 337 <xsl:with-param name="text" select="')'"/> 338 </xsl:call-template> 339 <xsl:call-template name="source-highlight"> 340 <xsl:with-param name="text" select="$postdeclarator"/> 341 </xsl:call-template> 342 <xsl:call-template name="highlight-text"> 343 <xsl:with-param name="text" select="';'"/> 344 </xsl:call-template> 345 </xsl:otherwise> 346 </xsl:choose> 347 </xsl:template> 348 349 <!-- Synopsis of function parameters, e.g., "(const T&, int x = 5)" --> 350 <xsl:template name="function-parameters"> 351 <!-- Indentation level of this parameter list --> 352 <xsl:param name="indentation"/> 353 354 <!-- True if we should include parameter names --> 355 <xsl:param name="include-names" select="true()"/> 356 357 <!-- True if we should wrap function parameters to the next line --> 358 <xsl:param name="wrap" select="true()"/> 359 360 <!-- True if we are printing the final output --> 361 <xsl:param name="final" select="false()"/> 362 363 <!-- Internal: The prefix to emit before a parameter --> 364 <xsl:param name="prefix" select="''"/> 365 366 <!-- Internal: The list of parameters --> 367 <xsl:param name="parameters" select="parameter"/> 368 369 <!-- Internal: The column we are on --> 370 <xsl:param name="column" select="$indentation"/> 371 372 <!-- Internal: Whether this is the first parameter on this line or not --> 373 <xsl:param name="first-on-line" select="true()"/> 374 375 <xsl:if test="$parameters"> 376 <!-- Information for this parameter --> 377 <xsl:variable name="parameter" select="$parameters[position()=1]"/> 378 <xsl:variable name="pack"> 379 <xsl:if test="$parameter/@pack=1"> 380 <xsl:choose> 381 <xsl:when test="$final"> 382 <xsl:call-template name="highlight-text"> 383 <xsl:with-param name="text" select="'...'"/> 384 </xsl:call-template> 385 </xsl:when> 386 <xsl:otherwise> 387 <xsl:text>...</xsl:text> 388 </xsl:otherwise> 389 </xsl:choose> 390 </xsl:if> 391 </xsl:variable> 392 <xsl:variable name="name"> 393 <xsl:if test="$include-names and $parameter/@name != ''"> 394 <xsl:text> </xsl:text><xsl:value-of select="$parameter/@name"/> 395 </xsl:if> 396 </xsl:variable> 397 398 <xsl:variable name="type" select="string($parameter/paramtype)"/> 399 400 <xsl:variable name="default"> 401 <xsl:choose> 402 <xsl:when test="$parameter/@default"> 403 <xsl:choose> 404 <xsl:when test="$final"> 405 <xsl:call-template name="highlight-text"> 406 <xsl:with-param name="text" select="concat(' = ', $parameter/@default)"/> 407 </xsl:call-template> 408 </xsl:when> 409 <xsl:otherwise> 410 <xsl:text> = </xsl:text> 411 <xsl:value-of select="$parameter/@default"/> 412 </xsl:otherwise> 413 </xsl:choose> 414 </xsl:when> 415 <xsl:when test="$parameter/default"> 416 <xsl:choose> 417 <xsl:when test="$final"> 418 <xsl:call-template name="highlight-text"> 419 <xsl:with-param name="text" select="' = '"/> 420 </xsl:call-template> 421 <xsl:apply-templates 422 select="$parameter/default/*|$parameter/default/text()" 423 mode="annotation"> 424 <xsl:with-param name="highlight" select="true()"/> 425 </xsl:apply-templates> 426 </xsl:when> 427 <xsl:otherwise> 428 <xsl:text> = </xsl:text> 429 <xsl:value-of select="string($parameter/default)"/> 430 </xsl:otherwise> 431 </xsl:choose> 432 </xsl:when> 433 </xsl:choose> 434 </xsl:variable> 435 436 <xsl:variable name="text" select="concat($type, $pack, $name, $default)"/> 437 438 <xsl:variable name="end-column" 439 select="$column + string-length($prefix) + string-length($text)"/> 440 441 <xsl:choose> 442 <!-- Parameter goes on this line --> 443 <xsl:when test="$first-on-line or ($end-column < $max-columns) 444 or not($wrap)"> 445 <xsl:choose> 446 <xsl:when test="$final"> 447 <xsl:call-template name="highlight-text"> 448 <xsl:with-param name="text" select="$prefix"/> 449 </xsl:call-template> 450 <xsl:apply-templates 451 select="$parameter/paramtype/*|$parameter/paramtype/text()" 452 mode="annotation"> 453 <xsl:with-param name="highlight" select="true()"/> 454 </xsl:apply-templates> 455 <xsl:copy-of select="$pack"/> 456 <xsl:value-of select="$name"/> 457 <xsl:copy-of select="$default"/> 458 </xsl:when> 459 <xsl:otherwise> 460 <xsl:value-of select="concat($prefix, $text)"/> 461 </xsl:otherwise> 462 </xsl:choose> 463 464 <xsl:call-template name="function-parameters"> 465 <xsl:with-param name="indentation" select="$indentation"/> 466 <xsl:with-param name="include-names" select="$include-names"/> 467 <xsl:with-param name="wrap" select="$wrap"/> 468 <xsl:with-param name="final" select="$final"/> 469 <xsl:with-param name="parameters" 470 select="$parameters[position()!=1]"/> 471 <xsl:with-param name="prefix" select="', '"/> 472 <xsl:with-param name="column" select="$end-column"/> 473 <xsl:with-param name="first-on-line" select="false()"/> 474 </xsl:call-template> 475 </xsl:when> 476 <!-- Parameter goes on next line --> 477 <xsl:otherwise> 478 <!-- The comma goes on this line --> 479 <xsl:choose> 480 <xsl:when test="$final"> 481 <xsl:call-template name="highlight-text"> 482 <xsl:with-param name="text" select="$prefix"/> 483 </xsl:call-template> 484 </xsl:when> 485 <xsl:otherwise> 486 <xsl:value-of select="$prefix"/> 487 </xsl:otherwise> 488 </xsl:choose> 489 <xsl:text> </xsl:text> 490 491 <!-- Indent and print the parameter --> 492 <xsl:call-template name="indent"> 493 <xsl:with-param name="indentation" select="$indentation"/> 494 </xsl:call-template> 495 <xsl:choose> 496 <xsl:when test="$final"> 497 <xsl:apply-templates 498 select="$parameter/paramtype/*|$parameter/paramtype/text()" 499 mode="annotation"> 500 <xsl:with-param name="highlight" select="true()"/> 501 </xsl:apply-templates> 502 <xsl:copy-of select="$pack"/> 503 <xsl:value-of select="$name"/> 504 <xsl:copy-of select="$default"/> 505 </xsl:when> 506 <xsl:otherwise> 507 <xsl:value-of select="concat($prefix, $text)"/> 508 </xsl:otherwise> 509 </xsl:choose> 510 511 <!-- Emit next parameter --> 512 <xsl:call-template name="function-parameters"> 513 <xsl:with-param name="indentation" select="$indentation"/> 514 <xsl:with-param name="include-names" select="$include-names"/> 515 <xsl:with-param name="wrap" select="$wrap"/> 516 <xsl:with-param name="final" select="$final"/> 517 <xsl:with-param name="parameters" 518 select="$parameters[position()!=1]"/> 519 <xsl:with-param name="prefix" select="', '"/> 520 <xsl:with-param name="column" 521 select="1 + string-length($text) + $indentation"/> 522 <xsl:with-param name="first-on-line" select="false()"/> 523 </xsl:call-template> 524 </xsl:otherwise> 525 </xsl:choose> 526 </xsl:if> 527 </xsl:template> 528 529 <!-- Function synopsis --> 530 <xsl:template match="function|method" mode="synopsis"> 531 <xsl:param name="indentation"/> 532 533 <!-- True if we should compact this function --> 534 <xsl:variable name="compact" 535 select="not (para|description|requires|effects|postconditions|returns| 536 throws|complexity|notes|rationale) and 537 ($boost.compact.function='1') and 538 not (local-name(.)='method')"/> 539 540 <xsl:choose> 541 <xsl:when test="$compact"> 542 <xsl:if test="purpose"> 543 <!-- Compact display outputs the purpose as a comment (if 544 there is one) and the entire function declaration. --> 545 <xsl:text> </xsl:text> 546 <xsl:call-template name="indent"> 547 <xsl:with-param name="indentation" select="$indentation"/> 548 </xsl:call-template> 549 550 <xsl:call-template name="highlight-comment"> 551 <xsl:with-param name="text"> 552 <xsl:text>// </xsl:text> 553 <xsl:apply-templates select="purpose/*|purpose/text()" 554 mode="purpose"/> 555 </xsl:with-param> 556 </xsl:call-template> 557 </xsl:if> 558 559 <xsl:call-template name="function"> 560 <xsl:with-param name="indentation" select="$indentation"/> 561 <xsl:with-param name="is-reference" select="true()"/> 562 </xsl:call-template> 563 </xsl:when> 564 <xsl:otherwise> 565 <xsl:call-template name="function"> 566 <xsl:with-param name="indentation" select="$indentation"/> 567 <xsl:with-param name="is-reference" select="false()"/> 568 </xsl:call-template> 569 </xsl:otherwise> 570 </xsl:choose> 571 </xsl:template> 572 573 <xsl:template match="overloaded-function|overloaded-method" mode="synopsis"> 574 <xsl:param name="indentation"/> 575 576 <xsl:variable name="name" select="@name"/> 577 578 <!-- True if we should compact this function --> 579 <xsl:variable name="compact" 580 select="not (para|description|requires|effects|postconditions|returns| 581 throws|complexity|notes|rationale) and 582 ($boost.compact.function='1') and 583 not (local-name(.)='overloaded-method')"/> 584 585 <xsl:choose> 586 <xsl:when test="$compact"> 587 <xsl:if test="purpose"> 588 <!-- Compact display outputs the purpose as a comment (if 589 there is one) and the entire function declaration. --> 590 <xsl:text> </xsl:text> 591 <xsl:call-template name="indent"> 592 <xsl:with-param name="indentation" select="$indentation"/> 593 </xsl:call-template> 594 595 <xsl:call-template name="highlight-comment"> 596 <xsl:with-param name="text"> 597 <xsl:text>// </xsl:text> 598 <xsl:apply-templates select="purpose" mode="annotation"/> 599 </xsl:with-param> 600 </xsl:call-template> 601 </xsl:if> 602 603 <xsl:for-each select="signature"> 604 <xsl:call-template name="function"> 605 <xsl:with-param name="indentation" select="$indentation"/> 606 <xsl:with-param name="is-reference" select="true()"/> 607 <xsl:with-param name="name" select="$name"/> 608 </xsl:call-template> 609 </xsl:for-each> 610 </xsl:when> 611 <xsl:when test="local-name(..)='namespace'"> 612 <xsl:variable name="link-to"> 613 <xsl:call-template name="generate.id"/> 614 </xsl:variable> 615 616 <xsl:for-each select="signature"> 617 <xsl:call-template name="function"> 618 <xsl:with-param name="indentation" select="$indentation"/> 619 <xsl:with-param name="is-reference" select="false()"/> 620 <xsl:with-param name="name" select="$name"/> 621 <xsl:with-param name="link-to" select="$link-to"/> 622 </xsl:call-template> 623 </xsl:for-each> 624 </xsl:when> 625 <xsl:otherwise> 626 <xsl:for-each select="signature"> 627 <xsl:call-template name="function"> 628 <xsl:with-param name="indentation" select="$indentation"/> 629 <xsl:with-param name="is-reference" select="false()"/> 630 <xsl:with-param name="name" select="$name"/> 631 </xsl:call-template> 632 </xsl:for-each> 633 </xsl:otherwise> 634 </xsl:choose> 635 </xsl:template> 636 637 <!-- Group free functions together under a category name (header synopsis)--> 638 <xsl:template match="free-function-group" mode="header-synopsis"> 639 <xsl:param name="class"/> 640 <xsl:param name="indentation"/> 641 <xsl:apply-templates select="function|overloaded-function" mode="synopsis"> 642 <xsl:with-param name="indentation" select="$indentation"/> 643 </xsl:apply-templates> 644 </xsl:template> 645 646 <!-- Constructors, destructor, and assignment operators --> 647 <xsl:template name="construct-copy-destruct-synopsis"> 648 <xsl:param name="indentation"/> 649 <xsl:if test="constructor|copy-assignment|destructor"> 650 <xsl:if test="typedef|static-constant"> 651 <xsl:text> </xsl:text> 652 </xsl:if> 653 <xsl:text> </xsl:text> 654 <xsl:call-template name="indent"> 655 <xsl:with-param name="indentation" select="$indentation"/> 656 </xsl:call-template> 657 <xsl:call-template name="highlight-comment"> 658 <xsl:with-param name="text"> 659 <xsl:text>// </xsl:text> 660 <xsl:call-template name="internal-link"> 661 <xsl:with-param name="to"> 662 <xsl:call-template name="generate.id"/> 663 <xsl:text>construct-copy-destruct</xsl:text> 664 </xsl:with-param> 665 <xsl:with-param name="text" select="'construct/copy/destruct'"/> 666 </xsl:call-template> 667 </xsl:with-param> 668 </xsl:call-template> 669 <xsl:apply-templates select="constructor" mode="synopsis"> 670 <xsl:with-param name="indentation" select="$indentation"/> 671 </xsl:apply-templates> 672 <xsl:apply-templates select="copy-assignment" mode="synopsis"> 673 <xsl:with-param name="indentation" select="$indentation"/> 674 </xsl:apply-templates> 675 <xsl:apply-templates select="destructor" mode="synopsis"> 676 <xsl:with-param name="indentation" select="$indentation"/> 677 </xsl:apply-templates> 678 </xsl:if> 679 </xsl:template> 680 681 <xsl:template name="construct-copy-destruct-reference"> 682 <xsl:if test="constructor|copy-assignment|destructor"> 683 <xsl:call-template name="member-documentation"> 684 <xsl:with-param name="name"> 685 <xsl:call-template name="anchor"> 686 <xsl:with-param name="to"> 687 <xsl:call-template name="generate.id"/> 688 <xsl:text>construct-copy-destruct</xsl:text> 689 </xsl:with-param> 690 <xsl:with-param name="text" select="''"/> 691 </xsl:call-template> 692 <xsl:call-template name="monospaced"> 693 <xsl:with-param name="text"> 694 <xsl:call-template name="object-name"/> 695 </xsl:with-param> 696 </xsl:call-template> 697 <xsl:text> </xsl:text> 698 <xsl:call-template name="access-name"/> 699 <xsl:text> construct/copy/destruct</xsl:text> 700 </xsl:with-param> 701 <xsl:with-param name="text"> 702 <orderedlist> 703 <xsl:apply-templates select="constructor" mode="reference"/> 704 <xsl:apply-templates select="copy-assignment" mode="reference"/> 705 <xsl:apply-templates select="destructor" mode="reference"/> 706 </orderedlist> 707 </xsl:with-param> 708 </xsl:call-template> 709 </xsl:if> 710 </xsl:template> 711 712 <xsl:template match="constructor" mode="reference"> 713 <xsl:call-template name="function.documentation"> 714 <xsl:with-param name="text"> 715 <para> 716 <xsl:call-template name="preformatted"> 717 <xsl:with-param name="text"> 718 <xsl:call-template name="function"> 719 <xsl:with-param name="indentation" select="0"/> 720 <xsl:with-param name="is-reference" select="true()"/> 721 <xsl:with-param name="constructor-for"> 722 <xsl:call-template name="object-name"/> 723 </xsl:with-param> 724 <xsl:with-param name="standalone" select="true()"/> 725 </xsl:call-template> 726 </xsl:with-param> 727 </xsl:call-template> 728 </para> 729 <xsl:call-template name="function-requirements"/> 730 </xsl:with-param> 731 </xsl:call-template> 732 </xsl:template> 733 734 <xsl:template match="copy-assignment" mode="reference"> 735 <xsl:call-template name="function.documentation"> 736 <xsl:with-param name="text"> 737 <para> 738 <xsl:call-template name="preformatted"> 739 <xsl:with-param name="text"> 740 <xsl:call-template name="function"> 741 <xsl:with-param name="indentation" select="0"/> 742 <xsl:with-param name="is-reference" select="true()"/> 743 <xsl:with-param name="copy-assign-for"> 744 <xsl:call-template name="object-name"/> 745 </xsl:with-param> 746 <xsl:with-param name="standalone" select="true()"/> 747 </xsl:call-template> 748 </xsl:with-param> 749 </xsl:call-template> 750 </para> 751 <xsl:call-template name="function-requirements"/> 752 </xsl:with-param> 753 </xsl:call-template> 754 </xsl:template> 755 756 <xsl:template match="destructor" mode="reference"> 757 <xsl:call-template name="function.documentation"> 758 <xsl:with-param name="text"> 759 <para> 760 <xsl:call-template name="preformatted"> 761 <xsl:with-param name="text"> 762 <xsl:call-template name="function"> 763 <xsl:with-param name="indentation" select="0"/> 764 <xsl:with-param name="is-reference" select="true()"/> 765 <xsl:with-param name="destructor-for"> 766 <xsl:call-template name="object-name"/> 767 </xsl:with-param> 768 <xsl:with-param name="standalone" select="true()"/> 769 </xsl:call-template> 770 </xsl:with-param> 771 </xsl:call-template> 772 </para> 773 <xsl:call-template name="function-requirements"/> 774 </xsl:with-param> 775 </xsl:call-template> 776 </xsl:template> 777 778 <!-- Templates for functions --> 779 <xsl:template name="function.documentation"> 780 <xsl:param name="text"/> 781 <xsl:choose> 782 <xsl:when test="count(ancestor::free-function-group) > 0 783 or count(ancestor::method-group) > 0 784 or local-name(.)='constructor' 785 or local-name(.)='copy-assignment' 786 or local-name(.)='destructor'"> 787 <listitem><xsl:copy-of select="$text"/></listitem> 788 </xsl:when> 789 <xsl:otherwise> 790 <xsl:copy-of select="$text"/> 791 </xsl:otherwise> 792 </xsl:choose> 793 </xsl:template> 794 795 <!-- Semantic descriptions of functions --> 796 <xsl:template name="function-requirements"> 797 <xsl:param name="namespace-reference" select="false()"/> 798 799 <xsl:if test="$namespace-reference=false()"> 800 <xsl:apply-templates select="purpose/*|purpose/text()"/> 801 </xsl:if> 802 803 <xsl:apply-templates select="description/*"/> 804 805 <xsl:if test="parameter/description|signature/parameter/description| 806 template/template-type-parameter/purpose| 807 template/template-nontype-parameter/purpose| 808 requires|effects|postconditions|returns|throws|complexity| 809 notes|rationale"> 810 <variablelist spacing="compact"> 811 <xsl:processing-instruction name="dbhtml"> 812 list-presentation="table" 813 </xsl:processing-instruction> 814 815 <!-- Document parameters --> 816 <xsl:if test="parameter/description|signature/parameter/description"> 817 <varlistentry> 818 <term>Parameters:</term> 819 <listitem> 820 <variablelist spacing="compact"> 821 <xsl:processing-instruction name="dbhtml"> 822 list-presentation="table" 823 </xsl:processing-instruction> 824 <xsl:for-each select="parameter|signature/parameter"> 825 <xsl:sort select="attribute::name"/> 826 <xsl:if test="description"> 827 <varlistentry> 828 <term> 829 <xsl:call-template name="monospaced"> 830 <xsl:with-param name="text" select="@name"/> 831 </xsl:call-template> 832 </term> 833 <listitem> 834 <xsl:apply-templates select="description/*"/> 835 </listitem> 836 </varlistentry> 837 </xsl:if> 838 </xsl:for-each> 839 </variablelist> 840 </listitem> 841 </varlistentry> 842 </xsl:if> 843 844 <!-- Document template parameters --> 845 <xsl:if test="template/template-type-parameter/purpose| 846 template/template-nontype-parameter/purpose"> 847 <varlistentry> 848 <term>Template Parameters:</term> 849 <listitem> 850 <variablelist spacing="compact"> 851 <xsl:processing-instruction name="dbhtml"> 852 list-presentation="table" 853 </xsl:processing-instruction> 854 <xsl:for-each select="template/template-type-parameter| 855 template/template-nontype-parameter"> 856 <xsl:sort select="attribute::name"/> 857 <xsl:if test="purpose"> 858 <varlistentry> 859 <term> 860 <xsl:call-template name="monospaced"> 861 <xsl:with-param name="text" select="@name"/> 862 </xsl:call-template> 863 </term> 864 <listitem> 865 <xsl:apply-templates select="purpose/*"/> 866 </listitem> 867 </varlistentry> 868 </xsl:if> 869 </xsl:for-each> 870 </variablelist> 871 </listitem> 872 </varlistentry> 873 </xsl:if> 874 875 <!-- Document rest of function's contract --> 876 <xsl:for-each select="requires|effects|postconditions|returns|throws|complexity| 877 notes|rationale"> 878 <varlistentry> 879 <term><xsl:call-template name="function.requirement.name"/>:</term> 880 <listitem> 881 <xsl:apply-templates select="./*|./text()" mode="annotation"/> 882 </listitem> 883 </varlistentry> 884 </xsl:for-each> 885 886 </variablelist> 887 </xsl:if> 888 889 <xsl:if test="para"> 890 <xsl:message> 891 <xsl:text>Warning: Use of 'para' elements in a function is deprecated. </xsl:text> 892 <xsl:text> Wrap them in a 'description' element.</xsl:text> 893 </xsl:message> 894 <xsl:call-template name="print.warning.context"/> 895 <xsl:apply-templates select="para"/> 896 </xsl:if> 897 898 </xsl:template> 899 900 <xsl:template name="function.requirement.name"> 901 <xsl:param name="node" select="."/> 902 <xsl:choose> 903 <xsl:when test="local-name($node)='requires'">Requires</xsl:when> 904 <xsl:when test="local-name($node)='effects'">Effects</xsl:when> 905 <xsl:when test="local-name($node)='postconditions'"> 906 <xsl:text>Postconditions</xsl:text> 907 </xsl:when> 908 <xsl:when test="local-name($node)='returns'">Returns</xsl:when> 909 <xsl:when test="local-name($node)='throws'">Throws</xsl:when> 910 <xsl:when test="local-name($node)='complexity'">Complexity</xsl:when> 911 <xsl:when test="local-name($node)='notes'">Notes</xsl:when> 912 <xsl:when test="local-name($node)='rationale'">Rationale</xsl:when> 913 <xsl:otherwise> 914 <xsl:message> 915 <xsl:text>Error: unhandled node type `</xsl:text> 916 <xsl:value-of select="local-name($node)"/> 917 <xsl:text>' in template function.requirement.name.</xsl:text> 918 </xsl:message> 919 </xsl:otherwise> 920 </xsl:choose> 921 </xsl:template> 922 923 <!-- Function reference --> 924 <xsl:template match="function|method" mode="reference"> 925 <!-- True if we should compact this function --> 926 <xsl:variable name="compact" 927 select="not (para|description|requires|effects|postconditions|returns| 928 throws|complexity|notes|rationale) and 929 ($boost.compact.function='1') and 930 not (local-name(.)='method')"/> 931 932 <xsl:if test="not ($compact)"> 933 <xsl:call-template name="function.documentation"> 934 <xsl:with-param name="text"> 935 <para> 936 <xsl:call-template name="preformatted"> 937 <xsl:with-param name="text"> 938 <xsl:call-template name="function"> 939 <xsl:with-param name="indentation" select="0"/> 940 <xsl:with-param name="is-reference" select="true()"/> 941 <xsl:with-param name="link-type" select="'anchor'"/> 942 <xsl:with-param name="standalone" select="true()"/> 943 </xsl:call-template> 944 </xsl:with-param> 945 </xsl:call-template> 946 </para> 947 <xsl:call-template name="function-requirements"/> 948 </xsl:with-param> 949 </xsl:call-template> 950 </xsl:if> 951 </xsl:template> 952 953 <!-- Reference for functions at namespace level --> 954 <xsl:template match="function" mode="namespace-reference"> 955 <!-- True if we should compact this function --> 956 <xsl:variable name="compact" 957 select="not (para|description|requires|effects|postconditions|returns| 958 throws|complexity|notes|rationale) and 959 ($boost.compact.function='1')"/> 960 961 <xsl:if test="not ($compact)"> 962 <xsl:call-template name="reference-documentation"> 963 <xsl:with-param name="name"> 964 <xsl:text>Function </xsl:text> 965 <xsl:if test="template"> 966 <xsl:text>template </xsl:text> 967 </xsl:if> 968 <xsl:call-template name="monospaced"> 969 <xsl:with-param name="text" select="@name"/> 970 </xsl:call-template> 971 </xsl:with-param> 972 <xsl:with-param name="refname"> 973 <xsl:call-template name="fully-qualified-name"> 974 <xsl:with-param name="node" select="."/> 975 </xsl:call-template> 976 </xsl:with-param> 977 <xsl:with-param name="purpose" select="purpose/*|purpose/text()"/> 978 <xsl:with-param name="anchor"> 979 <xsl:call-template name="generate.id"/> 980 </xsl:with-param> 981 <xsl:with-param name="synopsis"> 982 <xsl:call-template name="header-link"/> 983 <xsl:call-template name="function"> 984 <xsl:with-param name="indentation" select="0"/> 985 <xsl:with-param name="is-reference" select="true()"/> 986 <xsl:with-param name="link-type" select="'none'"/> 987 </xsl:call-template> 988 </xsl:with-param> 989 <xsl:with-param name="text"> 990 <xsl:call-template name="function-requirements"> 991 <xsl:with-param name="namespace-reference" select="true()"/> 992 </xsl:call-template> 993 </xsl:with-param> 994 </xsl:call-template> 995 </xsl:if> 996 </xsl:template> 997 998 <xsl:template match="overloaded-function" mode="reference"> 999 <xsl:variable name="name" select="@name"/> 1000 1001 <!-- True if we should compact this function --> 1002 <xsl:variable name="compact" 1003 select="not (para|description|requires|effects|postconditions|returns| 1004 throws|complexity|notes|rationale) and 1005 ($boost.compact.function='1')"/> 1006 1007 <xsl:if test="not ($compact)"> 1008 <xsl:call-template name="function.documentation"> 1009 <xsl:with-param name="text"> 1010 <para> 1011 <xsl:attribute name="id"> 1012 <xsl:call-template name="generate.id"/> 1013 </xsl:attribute> 1014 1015 <xsl:call-template name="preformatted"> 1016 <xsl:with-param name="text"> 1017 <xsl:for-each select="signature"> 1018 <xsl:call-template name="function"> 1019 <xsl:with-param name="indentation" select="0"/> 1020 <xsl:with-param name="is-reference" select="true()"/> 1021 <xsl:with-param name="name" select="$name"/> 1022 <xsl:with-param name="standalone" select="true()"/> 1023 </xsl:call-template> 1024 </xsl:for-each> 1025 </xsl:with-param> 1026 </xsl:call-template> 1027 </para> 1028 <xsl:call-template name="function-requirements"/> 1029 </xsl:with-param> 1030 </xsl:call-template> 1031 </xsl:if> 1032 </xsl:template> 1033 1034 <xsl:template match="overloaded-function" mode="namespace-reference"> 1035 <!-- True if we should compact this function --> 1036 <xsl:variable name="compact" 1037 select="not (para|description|requires|effects|postconditions|returns| 1038 throws|complexity|notes|rationale) and 1039 ($boost.compact.function='1')"/> 1040 1041 <xsl:variable name="name" select="@name"/> 1042 1043 <xsl:if test="not ($compact)"> 1044 <xsl:call-template name="reference-documentation"> 1045 <xsl:with-param name="name"> 1046 <xsl:text>Function </xsl:text> 1047 <xsl:if test="template"> 1048 <xsl:text>template </xsl:text> 1049 </xsl:if> 1050 <xsl:call-template name="monospaced"> 1051 <xsl:with-param name="text" select="@name"/> 1052 </xsl:call-template> 1053 </xsl:with-param> 1054 <xsl:with-param name="refname"> 1055 <xsl:call-template name="fully-qualified-name"> 1056 <xsl:with-param name="node" select="."/> 1057 </xsl:call-template> 1058 </xsl:with-param> 1059 <xsl:with-param name="purpose" select="purpose/*|purpose/text()"/> 1060 <xsl:with-param name="anchor"> 1061 <xsl:call-template name="generate.id"/> 1062 </xsl:with-param> 1063 <xsl:with-param name="synopsis"> 1064 <xsl:call-template name="header-link"/> 1065 <xsl:for-each select="signature"> 1066 <xsl:call-template name="function"> 1067 <xsl:with-param name="indentation" select="0"/> 1068 <xsl:with-param name="is-reference" select="true()"/> 1069 <xsl:with-param name="link-type" select="'none'"/> 1070 <xsl:with-param name="name" select="$name"/> 1071 </xsl:call-template> 1072 </xsl:for-each> 1073 </xsl:with-param> 1074 <xsl:with-param name="text"> 1075 <xsl:call-template name="function-requirements"> 1076 <xsl:with-param name="namespace-reference" select="true()"/> 1077 </xsl:call-template> 1078 </xsl:with-param> 1079 </xsl:call-template> 1080 </xsl:if> 1081 </xsl:template> 1082 1083 <xsl:template match="overloaded-method" mode="reference"> 1084 <xsl:variable name="name" select="@name"/> 1085 1086 <xsl:call-template name="function.documentation"> 1087 <xsl:with-param name="text"> 1088 <para> 1089 <xsl:call-template name="preformatted"> 1090 <xsl:with-param name="text"> 1091 <xsl:call-template name="anchor"> 1092 <xsl:with-param name="to"> 1093 <xsl:call-template name="generate.id"/> 1094 </xsl:with-param> 1095 </xsl:call-template> 1096 <xsl:for-each select="signature"> 1097 <xsl:call-template name="function"> 1098 <xsl:with-param name="indentation" select="0"/> 1099 <xsl:with-param name="is-reference" select="true()"/> 1100 <xsl:with-param name="name" select="$name"/> 1101 <xsl:with-param name="standalone" select="true()"/> 1102 </xsl:call-template> 1103 </xsl:for-each> 1104 </xsl:with-param> 1105 </xsl:call-template> 1106 </para> 1107 <xsl:call-template name="function-requirements"/> 1108 </xsl:with-param> 1109 </xsl:call-template> 1110 </xsl:template> 1111 1112 <!-- Group member functions together under a category name (synopsis)--> 1113 <xsl:template match="method-group" mode="synopsis"> 1114 <xsl:param name="indentation"/> 1115 <xsl:if test="count(child::*) > 0"> 1116 <xsl:text> </xsl:text> 1117 <xsl:text> </xsl:text> 1118 <xsl:call-template name="indent"> 1119 <xsl:with-param name="indentation" select="$indentation"/> 1120 </xsl:call-template> 1121 <xsl:call-template name="highlight-comment"> 1122 <xsl:with-param name="text"> 1123 <xsl:text>// </xsl:text> 1124 <xsl:call-template name="internal-link"> 1125 <xsl:with-param name="to"> 1126 <xsl:call-template name="generate.id"/> 1127 </xsl:with-param> 1128 <xsl:with-param name="text" select="string(@name)"/> 1129 </xsl:call-template> 1130 </xsl:with-param> 1131 </xsl:call-template> 1132 <xsl:apply-templates select="method|overloaded-method" 1133 mode="synopsis"> 1134 <xsl:with-param name="indentation" select="$indentation"/> 1135 </xsl:apply-templates> 1136 </xsl:if> 1137 </xsl:template> 1138 1139 <!-- Group member functions together under a category name (reference)--> 1140 <xsl:template match="method-group" mode="reference"> 1141 <xsl:if test="count(child::*) > 0"> 1142 <xsl:call-template name="member-documentation"> 1143 <xsl:with-param name="name"> 1144 <xsl:call-template name="anchor"> 1145 <xsl:with-param name="to"> 1146 <xsl:call-template name="generate.id"/> 1147 </xsl:with-param> 1148 <xsl:with-param name="text" select="''"/> 1149 </xsl:call-template> 1150 <xsl:call-template name="monospaced"> 1151 <xsl:with-param name="text"> 1152 <xsl:call-template name="object-name"/> 1153 </xsl:with-param> 1154 </xsl:call-template> 1155 <xsl:text> </xsl:text> 1156 <xsl:value-of select="@name"/> 1157 </xsl:with-param> 1158 <xsl:with-param name="text"> 1159 <orderedlist> 1160 <xsl:apply-templates select="method|overloaded-method" 1161 mode="reference"/> 1162 </orderedlist> 1163 </xsl:with-param> 1164 </xsl:call-template> 1165 </xsl:if> 1166 </xsl:template> 1167 1168 <!-- Group free functions together under a category name (synopsis)--> 1169 <xsl:template match="free-function-group" mode="synopsis"> 1170 <xsl:param name="class"/> 1171 <xsl:param name="indentation"/> 1172 <xsl:text> </xsl:text> 1173 <xsl:text> </xsl:text> 1174 <xsl:call-template name="indent"> 1175 <xsl:with-param name="indentation" select="$indentation"/> 1176 </xsl:call-template> 1177 <xsl:call-template name="highlight-comment"> 1178 <xsl:with-param name="text"> 1179 <xsl:text>// </xsl:text> 1180 <xsl:call-template name="internal-link"> 1181 <xsl:with-param name="to"> 1182 <xsl:call-template name="generate.id"/> 1183 </xsl:with-param> 1184 <xsl:with-param name="text" select="string(@name)"/> 1185 </xsl:call-template> 1186 </xsl:with-param> 1187 </xsl:call-template> 1188 <xsl:apply-templates select="function|overloaded-function" mode="synopsis"> 1189 <xsl:with-param name="indentation" select="$indentation"/> 1190 </xsl:apply-templates> 1191 </xsl:template> 1192 1193 <!-- Group free functions together under a category name (reference)--> 1194 <xsl:template match="free-function-group" mode="reference"> 1195 <xsl:param name="class"/> 1196 <xsl:call-template name="member-documentation"> 1197 <xsl:with-param name="name"> 1198 <xsl:call-template name="anchor"> 1199 <xsl:with-param name="to"> 1200 <xsl:call-template name="generate.id"/> 1201 </xsl:with-param> 1202 <xsl:with-param name="text" select="''"/> 1203 </xsl:call-template> 1204 <xsl:call-template name="monospaced"> 1205 <xsl:with-param name="text" select="$class"/> 1206 </xsl:call-template> 1207 <xsl:value-of select="concat(' ',@name)"/> 1208 </xsl:with-param> 1209 <xsl:with-param name="text"> 1210 <orderedlist> 1211 <xsl:apply-templates select="function|overloaded-function" 1212 mode="reference"/> 1213 </orderedlist> 1214 </xsl:with-param> 1215 </xsl:call-template> 1216 </xsl:template> 1217</xsl:stylesheet> 1218