"Dimitrie O. Paun" a écrit :
On September 18, 2002 04:10 am, Eric POUECH wrote:
IMO, most of the documentation (even the internals description, status of DLL) should be made in the DocBook form
I don't think this is right. Documenetation that is meant for the user should go into .sgml, no disagreement here. Documentation that is meant for the ongoing developement of a DLL (something like the TODO list, or a few comments on the internal structure, or some tips, etc.) should go as plain text as close as possible to the code that it's documenting.
I can not stress how important that is. I find this "developer" documentation useful beyon words: as I read through the code, it gives me ideas on what to work, I keep it _updated_. On the other hand, I've never even read 50% of the .sgml documentation even once. But even if I do, it will never have the "current" status of the one embedded in the/close to the code. As I said before, this thing has been tried numerous times before, and everybody reached the conclusion that the documentation pertaining to code should be as close to the code that it's documenting (see javadoc et. Co.).
we mostly agree: - my point was to remove (mainly) the README and stuff like that from the module dir - I know quite a few places where the README (in the module) is pure end-user doc (winedbg, winedump to name a few). - therefore, most of the DLL status (in terms of what's missing...) can well be IN the code (commctrl did it to some extent IIRC) - perhaps, what we could add is a structured way to describe this "in code" documentation (so we can extract it later on if needed) - finally, what's also missing is automatic generation of online docs (for example, when a new Wine release comes out)
A+