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

[Matt Jordan]

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

(Updated July 17, 2012, 9:34 a.m.)


Review request for Asterisk Developers and rmudgett.


Changes
-------

Resolved Richard's findings.


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 (updated)
-----

  /trunk/channels/chan_sip.c 370048 
  /trunk/doc/appdocsxml.dtd 370048 
  /trunk/main/message.c 370048 
  /trunk/main/xmldoc.c 370048 
  /trunk/res/res_xmpp.c 370048 

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/20120717/860d7dea/attachment.htm>