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

[Brandon Kruse]

>----- 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.


If we get these two, it will be a very nice feature to have, and architectural change to have.

-Brandon