[asterisk-dev] Asterisk.org online Doxygen Docs

[Matthew Jordan]

On 10/10/2012 12:56 AM, Olle E. Johansson wrote:
> 
> 10 okt 2012 kl. 04:54 skrev Matthew Jordan <mjordan at digium.com>:
> 
> 
> 
> 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.

At the same time, having things documented in multiple places is why
things often end up out of sync.  It is a large enough task to keep
documentation up to date and accurate in a single place; having to do so
in multiple places doesn't seem sustainable.

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

The channel variable document was quite good (although it wasn't in
doxygen either, but that's a different problem).  Most of the
information contained in it is on the wiki; however, I'm sure there's
something in it that isn't.  That may be the case for other documents as
well.

In general, I'd prefer to focus on putting that information on the wiki.
 It provides much greater flexibility not only in keeping the
information up to date, i.e., you don't have to have subversion commit
access to make documentation updates, but it also has the ability to
embed diagrams, code markup, tables, etc.

I understand some people prefer this information to live in the source
tree - however, what I want to avoid is doubling the maintenance effort
on documentation.  If there's a way to accomplish that without having to
enter the information in multiple locations, I'd support it.


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