[asterisk-dev] managerEvent XML documentation

[Matthew Jordan]

On Fri, Aug 1, 2014 at 5:47 PM, Corey Farrell <git at cfware.com> wrote:
>
> Hello everyone,
>
> As part of r3811 I'm fixing build_tools/get_documentation so it picks
> up every /*** DOCUMENTATION ***/ block, instead of just the first from
> each file.  As a side-effect this picked up some validation error's
> that were previously unnoticed.  One of them is in main/logger.c, the
> LogChannel event documentation.  This event has two variations -
> "Enable: yes", and "Enable: no\nReason: %d - %s".  Personally I feel
> it would be better if we had separate LogChannelStart and
> LogChannelStop events, but I suspect it's too late for that.  Assuming
> we keep the single event with two variations, how should it be
> documented?
>
> https://reviewboard.asterisk.org/r/3811/
>
> Note: although the fix to build_tools/get_documentation could apply to
> 11/12, this caused the build to fail due to many documentation
> validation errors.  I'm not against eventually back-porting the fix,
> but for now I'm proposing it for trunk only as I don't have time to
> audit/fix/test the documentation in those versions.
>

I commented on the review, but I'll re-post here as well:

{quote}
Keep in mind that they are documented in two places because the same
event is raised under multiple conditions. Note the different synopsis
elements:

<synopsis>Raised when a logging channel is re-enabled after a reload
operation.</synopsis>
<synopsis>Raised when a logging channel is disabled.</synopsis>

Additionally, there is an additional field when the LogChannel event
is raised when being disabled (Reason).

The Python scripts combine these into a single event documentation
element. You can see this in the Asterisk 11 event documentation:

https://wiki.asterisk.org/wiki/display/AST/Asterisk+11+ManagerEvent_LogChannel

Whether or not these should be renamed into two separate events is a
fair point. It's certainly the approach we've gone with for the
majority of events in AMI 2.X, and for any new events that are added.
However, splitting these up now would be a breaking change to the API.
If we're going to go do that, we should (a) do it in Asterisk 14, and
(b) make sure that we do one comprehensive change.
{quote}

I'm not sure how you would be getting documentation validation errors.
I suspect it is because you aren't combining the
<managerEventInstance> elements into children of a <managerEvent>. The
python script(s) do this and the XML document generated is valid (and
validated), so I don't think the issue is in the code.

There's a reason why I went with a Python script over awk! :-)

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org