[asterisk-dev] Asterisk.org online Doxygen Docs

[Olle E. Johansson]

10 okt 2012 kl. 04:54 skrev Matthew Jordan <mjordan at digium.com>:

> On 10/02/2012 08:50 AM, Andrew Latham wrote:
>> On Tue, Oct 2, 2012 at 9:43 AM, Andrew Latham <lathama at gmail.com> wrote:
> 
>> 
>> BTW
>> 
>> One page I did add last night was
>> http://www.asterisk.org/doxygen/trunk/asterisk_community_resources.html
>> and I would enjoy feed back to the ticket
>> https://issues.asterisk.org/jira/browse/ASTERISK-20259 if you feel
>> something needs added, removed or updated there.
>> 
> 
> So, I'm not entirely sure that the Asterisk Community Resources page is
> appropriate for doxygen documentation.
> 
> 1) It reproduces content already on the mailman list page - which is
> linked from that document.  If lists are added or removed, the content
> in doxygen is (once again) out of date.  In general, information should
> only exist in a single place.
Agree, the list will be hard to keep up to date.
> 
> 2) Community members may find their way to community related information
> via files included with the source, but they're much more likely to find
> it via a more traditional website.  Having it in doxygen once again
> results in reproduction of information.
Which is GOOD!!! The Doxygen will be part of any source code kit. The source code seem
to travel alone to many dark places. Any place where we can point people in this direction is a good thing.

> 
> While I'm thrilled that you've taken on a lot of documentation cleanup
> work, I think we need to be careful about reproducing documentation that
> either already exists or belongs in a different location.  In general,
> the doxygen produced documentation is a resource that documents and
> tracks the version of the code its associated with.  This means that
> while its appropriate for documenting the APIs (headers) in Asterisk, I
> don't think its appropriate for information that does not uniquely
> reside in the Asterisk repository.


I think you are wrong. Since there was a reduction in documentation in the source
code - the wiki move - it can't hurt to add. Do remember that the code lives it's own
life and is quite often the only thing people have.

I encourage any attempt to expand the in-source documentation. I still miss the
channel variable document that used to live in the source. It should come back,
so it's always available for anyone.

/O