{aadocumentation:stringexpand}

Description

Generates inline reference documentation for another stringexpand command, read from that command source PHPDoc comments. Pass the target command keyword as the single parameter. aadocumentation builds the class name (AA_Stringexpand_ followed by the keyword), reflects its class docblock and its expand-method docblock, and returns an XML fragment. The root element is cmd with a name attribute equal to the keyword you passed. Free text before the first at-tag becomes a text element; every at-tag (param, return, usage, and so on) becomes an element named after the tag carrying the rest of that line. If the keyword matches no class, the result is just the empty shell, cmd name=keyword closed immediately. This command is experimental and marked unfinished in the source: the parser is literal, so docblock punctuation can leak into the text, and the output only reflects whatever comments the target class happens to carry.

Parameters

stringexpand required

The keyword of the command you want documented, for example trim or foreach. aadocumentation turns it into a class name (AA_Stringexpand_ plus the keyword, dashes removed) and reflects that class PHPDoc. The keyword is echoed verbatim into the name attribute of the returned cmd element. An unknown keyword is not an error: you get the empty shell cmd name=keyword. Empty or omitted yields cmd name= with an empty name.

Examples

virtual{aadocumentation:trim}

Expected(an XML cmd element named trim wrapping text and param children built from the class PHPDoc; for example a text element trims whitespaces form begin and end of the string, the param string string, and the param chars line)

Actual rims whitespaces form begin and end of the string */@param string $stringstring $chars

The real use: pass a command keyword and get its PHPDoc as XML. The class docblock and the expand-method docblock are both reflected. Notice the engine parser is literal: the trailing comment terminator from the source leaks into the first text element, and the @param line for chars became a param element (the tag name is the first word). Marked illustrative because the output mirrors whatever comments the trim class currently carries, so it is not a stable assertion.

virtual{trim:{aadocumentation:missingcmd}}

Expected(the self-closed empty shell: an opening cmd tag with name="missingcmd" and no child elements)

Actual

The same empty shell, shown as text rather than measured. Because the output is an XML tag the rendered page strips it from the live Actual, so this is marked illustrative; the Expected box shows the exact shell aadocumentation returns for a keyword that matches no class.

test{strlen:{aadocumentation:xyz}}

Expected19

Actual19

The keyword you pass becomes the name attribute of the cmd element verbatim. For the unknown keyword xyz the whole output is a newline, cmd name=xyz self-closed, a newline: 16 fixed characters plus the 3-letter name, so strlen is 19. Compare with the 4-letter nope example, which is 20.

test{strlen:{aadocumentation:nope}}

Expected20

Actual20

An unrecognised keyword is not an error. aadocumentation returns just the shell, a newline plus cmd name=nope self-closed plus a newline. That is 16 fixed characters around the 4-letter name, so strlen is 20. This length is independent of any docblock, which makes it a stable test.

← All expressions