documentation dir

[Eric Pouech]

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