[asterisk-dev] How much backporting of Doxygen updates should I do?

[Andrew Latham]

On Tue, Oct 30, 2012 at 1:31 PM, Matthew Jordan <mjordan at digium.com> wrote:
> On 10/30/2012 10:56 AM, Andrew Latham wrote:
>> All
>>
>> I have been hammering away on the Doxygen docs and still have a lot to
>> do.  I have stripped away layers of defunct documentation and noted
>> where there are swaths missing.  How far back in the Asterisk branches
>> should i push my updates.  A large portion of the work is _NOT_ code
>> specific.  For example many text files were removed in the 1.6.2
>> release but still mentioned in the Doxygen documentation.
>
> I think I might need to clarify something here again.
>
> Documentation that is not code specific should not duplicate content
> anywhere else, particularly content that exists on the Asterisk website
> or the Asterisk wiki.  (The same, in reverse, applies to code
> documentation - but that's a different story).
>
> The reason why that content was removed may be a bit murky, but for
> several years now the content has been migrated to other sources.
> Reversing this change is not appropriate.  Having content duplicated is
> not appropriate.
>
> If you would like the content on the wiki delivered with the source
> that's fine - a roundtrip mechanism can be worked out that exports the
> content into the source tree.  But wholesale replacing the /doc folder
> was not the intent of the janitor project on the wiki, nor is it a
> change that I want to see occur.
>
> All that being said, if the content does not belong on the Asterisk
> website or the Asterisk wiki, then its certainly a candidate for
> inclusion in the Asterisk source.  However, I feel like we're getting
> dangerously close to including content that was removed from that
> location a long time ago for a reason, and I really don't want to have
> that debate again.
>
> --
> 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

I do follow what you are saying Matt.  I am actually poking at a
slightly different topic.  The Doxygen configuration, and code blocks
call on content that is no longer included ie: CODINGGUIDELINES.txt as
quick example.  I am only looking to do the following.

1. Fix markup errors.
2. Remove reference or link to proper content
3. Spelling and language issues

So to paint a picture with an example.  If there is a "\ref CDR
Backends" that is a page that "\include CDR_BACKENDS.TXT" then that is
what I need to fix, via a link to the wiki or what ever docs are
correct.

We are really on the same page.  If you want just add me to google
chat and hit me up anytime.

-- 
~ Andrew "lathama" Latham lathama at gmail.com http://lathama.net ~