Re: [AD] Documentation system 2009

[Peter Wang <novalazy@xxxxxxxxxx>]

On 2009-01-12, Elias Pschernig <elias.pschernig@xxxxxxxxxx> wrote:
> On Sat, 2009-01-10 at 11:49 +1100, Peter Wang wrote:
> > 
> > OPTIONAL FEATURE
> > 
> > I do like to be able to read inline descriptions of functions, as long
> > as they aren't too long and clutter up the entire screen.  Since we're
> > using Natural Docs markers anyway, I have a script that can reinsert
> > text from func.* (etc.) files back into source code.  Currently it just
> > inserts the first paragraph into place, but it could be changed.
> > 
> > Of course, then you could generate Natural Docs too if you like.  Pandoc
> > and Natural Docs use different markup so you would lose some formatting,
> > but it should still be readable.
> > 
> 
> I see two problems with this:
> 
> - People mistakenly updating a code comment.
> - People forgetting to run the sync script after updating documentation.
> 
> The second one would be easily solved with a daily cron-job like "svn
> up; run-sync-script; scn ci" I guess, but the first one concerns me a
> bit. I tend to automatically fix grammar/typo mistakes whenever I see
> them, and likely wouldn't be aware if I do so in a real comment or a
> read-only one - and then such changes would be silently lost and never
> show up in the actual documentation. 
> 
> Instead of a more sophisticated solution where the sync script somehow
> makes a diff against the last synced version, maybe there should at
> least be something like this on top of such comments:
> 
> !AUTOMATICALLY PASTED COMMENT, TO MODIFY EDIT <filename> INSTEAD!

I agree, but the comment should be more subtle.  In case anyone still
wants to generate Natural Docs (anyone?), we should hide that comment
from Natural Docs, say, by putting it in a separate comment.

Eh, maybe it's not worthwhile.  Mainly I like to be able to jump to a
function and read its documentation, but we could easily generate tags
files from the *.txt files, too, or use the man pages.

Peter