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