[asterisk-dev] [Code Review] Add the ability to specify technology specific documentation

[rmudgett]

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



/trunk/main/xmldoc.c
<https://reviewboard.asterisk.org/r/2049/#comment12799>

    This is just a styling preference and could be ignored:
    Why indent more than one level on a line continuation?


- rmudgett


On July 19, 2012, 9:30 a.m., Matt Jordan wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviewboard.asterisk.org/r/2049/
> -----------------------------------------------------------
> 
> (Updated July 19, 2012, 9:30 a.m.)
> 
> 
> Review request for Asterisk Developers and rmudgett.
> 
> 
> Summary
> -------
> 
> A number of applications/AMI commands in Asterisk have specific behavioral differences depending on the resource or channel technology those applications are executed on.  For example, while the MessageSend application is technology agnostic, how the channel drivers that support the MessageSend application behave is dependent on those the protocols and the channel driver implementation.  Prior to this patch, those details were either documented in the application/command documentation itself, or were left undocumented.
> 
> Documenting technology specific information with the items that use that information tends to be problematic for the following reasons:
> 1) Sometimes, the documentation more naturally belongs in the channel driver or resource that implements that technology, as opposed to the consumer that uses it.
> 2) There may be multiple consumers that produce the technology specific behavior.  It is not always clear who should provide the documentation for a technology specific behavior when multiple applications/commands share that behavior.  This leads to confusion between documented applications, or inconsistency.  For example, many technology specific behaviors documented for the Dial application can also apply to the Originate manager command (and possible FollowMe or Queue as well).
> 
> This patch adds a new element to the documentation schema, <info/>.  An info node is essentially a piece of technology specific reference information that can be included by any top level XML documentation node.  For example, the MessageSend application has historically had a note describing how the SIP channel driver interprets the From: field:
> 
> <note>
>     <para>For SIP the from parameter can be a configured peer name
> 	or in the form of "display-name" &lt;URI&gt;.</para>
> </note>
> 
> This information was replicated for the MessageSend AMI command.  As the information is SIP specific information, it may be beneficial to document this information in chan_sip.  As such, this can now be represented as an info node:
> 
> <info name="SIPMessageFromInfo" language="en_US" tech="SIP">
> 	<para>The <literal>from</literal> parameter can be a configured peer name
> 		or in the form of "display-name" &lt;URI&gt;.</para>
> </info>
> 
> The MessageSend application/command can then reference this information using standard XInclude:
> 
> <xi:include xpointer="xpointer(/docs/info[@name='XMPPMessageToInfo'])" />
> 
> Note that while an application/command can use XInclude to pull the <info/> elements in, it is still possible to document the <info/> elements with the application/commands itself, as has been done historically.
> 
> An example of how this appears for the AMI command MessageSend is shown below.  Note that technology specific information is given yellow markup in the CLI, in a manner similar to the <note/> elements.
> 
> *CLI> manager show command MessageSend 
> [Syntax]
> Action: MessageSend
> [ActionID:] <value>
> To: <value>
> [From:] <value>
> [Body:] <value>
> [Base64Body:] <value>
> [Variable:] <value>
> 
> [Synopsis]
> Send an out of call message to an endpoint. 
> 
> [Description]
> Not available
> 
> [Arguments]
> ActionID
>     ActionID for this transaction. Will be returned.
> To
>     The URI the message is to be sent to.
>         Technology: SIP
>         Specifying a prefix of 'sip:' will send the message as a
>         SIP MESSAGE request.
>         Technology: XMPP
>         Specifying a prefix of 'xmpp:' will send the message as an
>         XMPP chat message.
> From
>     A From URI for the message if needed for the message technology being
>     used to send this message.
>         Technology: SIP
>         The 'from' parameter can be a configured peer name or in
>         the form of "display-name" <URI>.
> Body
>     The message body text.  This must not contain any newlines as that
>     conflicts with the AMI protocol.
> Base64Body
>     Text bodies requiring the use of newlines have to be base64 encoded
>     in this field.  Base64Body will be decoded before being sent out.
>     Base64Body takes precedence over Body.
> Variable
>     Message variable to set, multiple Variable: headers are allowed.
>     The header value is a comma separated list of name=value pairs.
> 
> [See Also]
> Not available
> 
> 
> Diffs
> -----
> 
>   /trunk/channels/chan_sip.c 370240 
>   /trunk/doc/appdocsxml.dtd 370240 
>   /trunk/main/message.c 370240 
>   /trunk/main/xmldoc.c 370240 
>   /trunk/res/res_xmpp.c 370240 
> 
> Diff: https://reviewboard.asterisk.org/r/2049/diff
> 
> 
> Testing
> -------
> 
> 
> Thanks,
> 
> Matt
> 
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20120719/08b9d9a3/attachment.htm>