[asterisk-dev] [Code Review] 3807: xmldoc: Add support for an <example> tag in the Asterisk XML documentation

[Matt Jordan]

> On July 28, 2014, 11:02 a.m., opticron wrote:
> > /trunk/funcs/func_jitterbuffer.c, line 69
> > <https://reviewboard.asterisk.org/r/3807/diff/3/?file=65593#file65593line69>
> >
> >     The 'language' attribute should probably be "DialPlan" for these.

Nope.

language only has semantic meaning by things that can parse it. For the CLI, it has no meaning. For the wiki, the value is "text".


> On July 28, 2014, 11:02 a.m., opticron wrote:
> > /trunk/main/xmldoc.c, line 1460
> > <https://reviewboard.asterisk.org/r/3807/diff/3/?file=65594#file65594line1460>
> >
> >     Why the extra variable?

It allows you to iteratively traverse the children of the node without losing who the original parent was:

for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {

We *could* theoretically get away with not doing this in this routine, but this:
a) Matches the nomenclature used in all other functions
b) Makes it easy to address the original pointer to the node if needed in the future.


- Matt


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviewboard.asterisk.org/r/3807/#review12885
-----------------------------------------------------------


On July 27, 2014, 9:28 p.m., Matt Jordan wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviewboard.asterisk.org/r/3807/
> -----------------------------------------------------------
> 
> (Updated July 27, 2014, 9:28 p.m.)
> 
> 
> Review request for Asterisk Developers.
> 
> 
> Repository: Asterisk
> 
> 
> Description
> -------
> 
> This patch adds support for an <example /> tag in the XML documentation schema.
> 
> For CLI help, this doesn't change the formatting too much:
>  - Preceeding white space is removed
>  - Unlike with para elements, new lines are preserved
> 
> However, having an <example /> tag in the XML schema allows for the wiki documentation generation script to surround the documentation with {code} or {noformat} tags, generating much better content for the wiki - and allowing us to put dialplan examples (and other code snippets, if desired) into the documentation for an application/function/AMI command/etc.
> 
> 
> Diffs
> -----
> 
>   /trunk/main/xmldoc.c 419680 
>   /trunk/funcs/func_jitterbuffer.c 419680 
>   /trunk/doc/appdocsxml.dtd 419680 
> 
> Diff: https://reviewboard.asterisk.org/r/3807/diff/
> 
> 
> Testing
> -------
> 
> Updated the JITTERBUFFER function. It now displays its dialplan examples in a single example block in the CLI help.
> 
> 
> Thanks,
> 
> Matt Jordan
> 
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20140728/e9167af8/attachment.html>