[asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world

[Tilghman Lesher]

On Monday 14 July 2008 16:51:29 Michiel van Baak wrote:
> On 16:10, Mon 14 Jul 08, Tilghman Lesher wrote:
> > On Monday 14 July 2008 15:19:02 Brandon Kruse wrote:
> > > >----- Original Message -----
> > > >From: "Russell Bryant" <russell at digium.com>
> > > >To: "Asterisk Developers Mailing List" <asterisk-dev at lists.digium.com>
> > > >Sent: Sunday, July 13, 2008 2:02:21 PM GMT -06:00 US/Canada Central
> > > >Subject: Re: [asterisk-dev] XML documentation of
> > > > apps/functions/the_rest_of_the_world
> > > >
> > > >On Jul 12, 2008, at 7:43 PM, Michiel van Baak wrote:
> > > >> Me myself is not really happy with this, but I can understand the
> > > >> reason
> > > >> why this would be needed.
> > > >> I think this takes some of the more flexible and cool stuff we can
> > > >> do, but on the other hand the trouble we could get from it may be
> > > >> worse.
> > > >
> > > >Well hopefully we can come up with a solution where don't lose the
> > > >flexibility you guys have been working toward, while also avoiding the
> > > >complexities of having the documentation, including the argument and
> > > >option meta data, not strictly tied to the module it pertains to.
> > > >
> > > >> I'll talk it over with bkruse to see what we can do here.
> > > >>
> > > >> As soon as we come up with something we will post it here for
> > > >> review.
> > > >
> > > >Sounds good.  Of course, if anyone else has any proposals on the
> > > >mechanics of doing this, please propose them here.
> > >
> > > Ok, very good suggestions. I did not mean to seem to get angry with
> > > tzafrir, he is my buddy, I am just on vacation, and it's suckin :P
> > >
> > > As Kevin mentioned, it would be great to be able to access the
> > > documentation from the actual compiled modules, so that we do not have
> > > a file.xml anywhere.
> > >
> > > I think it IS great, however, to have the ABILITY to get the
> > > documentation OUT of the module, and into a file in a parseable format.
> > >
> > > Accomplishing this means two things.
> > >
> > > 1) We do what Kevin mentioned and we access the documentation from the
> > > actual module.
> > >
> > > 2) Be able to export that documentation on build-time OR runtime
> > > (maybe?) to an external file with version information, so nothing gets
> > > confused. If we are going to do all this, let us make sure we do not
> > > make the same mistake many do, and try to get the version information
> > > right the first time, which will be a HUGE benefit to us.
> >
> > I think you misunderstood the concept.  Initially, in the source, the
> > documentation is held in some format.  It may be XML, it might be
> > something else.  At compile/link time, the documentation (for all
> > languages) will be loaded into the object file format, either embedded as
> > strings within the data section, or embedded into its own section within
> > the object file. For documentation that is queried during the Asterisk
> > runtime, it will be accessed directly from this module.  In other words,
> > when it comes to "core show application Foo", very little changes from
> > the current method. There is no XML to be parsed; the text is simply
> > displayed.  The only big change will be that the documentation embedded
> > into the module may be in multiple languages.
> >
> > The documentation still exists in the source directory in XML format and
> > may be exported to other formats (Postscript, PDF, Docbook, etc.).  So
> > all that we'd really be changing at this stage is where the documentation
> > is stored within the source; instead of the documentation stored as a
> > string within a C source file, the documentation will be stored within an
> > external XML file. Only at compile/link time will the documentation be
> > added directly to the module.
> >
> > This makes it easy to export the documentation to other formats, while at
> > the same time, not dramatically increasing the amount of processing the
> > Asterisk binary needs to do in order to display documentation.  I think
> > that provides a nice balance between being able to do more things with
> > the embedded documentation (and making the documentation easier to update
> > and internationalize) and ensuring that there is no confusion or extra
> > processing required by the Asterisk binary to display its own
> > documentation.
>
> Like this post ?
> http://lists.digium.com/pipermail/asterisk-dev/2008-July/033948.html
>
> bkruse and me had some talk about it and this is the gist of it.

I don't think there's any need to keep the documentation directly within the
source file itself.  In fact, I think that's where having a separate XML file
would be beneficial, in terms of not requiring the documenteurs to edit
source files in order to update documentation.

-- 
Tilghman