| Re: [AD] Documentation system 2009 |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
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!
--
Elias Pschernig <elias@xxxxxxxxxx>