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.).
"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+
On September 19, 2002 01:28 pm, Eric Pouech wrote:
we mostly agree:
Yeap.
- my point was to remove (mainly) the README and stuff like that from
the module dir
I don't have a problem with that, but if it's general info for developers working on that DLL, where do you put it?
- I know quite a few places where the README (in the module) is pure
end-user doc (winedbg, winedump to name a few).
True. I think those need to become man pages.
- 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)
Indeed. As I said, commctrl is great in that regard.
- perhaps, what we could add is a structured way to describe this
"in code" documentation (so we can extract it later on if needed)
Yes, but it's getting complicated. I was just looking to clean up things a bit :)
- finally, what's also missing is automatic generation of online docs
(for example, when a new Wine release comes out)
I've been toying with that idea for years...
- perhaps, what we could add is a structured way to describe this
"in code" documentation (so we can extract it later on if needed)
Yes, but it's getting complicated. I was just looking to clean up things a bit :)
- finally, what's also missing is automatic generation of online docs
(for example, when a new Wine release comes out)
I've been toying with that idea for years...
What about doxygen? It can extract all infos if marked for that and generate HTML, man, LaTex, and newly it's also possible to put out all raw data in XML so a script or so can format it to any desired output.
bye Fabi
- my point was to remove (mainly) the README and stuff like that from
the module dir
I don't have a problem with that, but if it's general info for developers working on that DLL, where do you put it?
you can leave it as a README, but it sounds it's rarely updated I'd suggest putting it in the "main.c" file (there's in most of the cases such a file). To cope with the "it's hard to find argument", we could generate such a reference list (from parsing content of C files)
- perhaps, what we could add is a structured way to describe this
"in code" documentation (so we can extract it later on if needed)
Yes, but it's getting complicated. I was just looking to clean up things a bit :)
another can of worms ;-) (and yes stuff like doxygen could do it)
A+
I've been toying with that idea for years...
BTW, I have an winehq adapted (from a color/style point of view) docbook.css file so if someone wants to toy really with that, let me know
A+
-
Dimitrie O. Paun -
Eric Pouech -
Fabian Cenedese