From: "Alexandre Julliard" julliard@winehq.org
Log message: Merged palette option processing into the main configuration code.
Hmm, these don't seem to have the magic comments, is this intentional?
"Dimi Paun" dimi@lattica.com writes:
From: "Alexandre Julliard" julliard@winehq.org
Log message: Merged palette option processing into the main configuration code.
Hmm, these don't seem to have the magic comments, is this intentional?
They do, the magic comment is on the RegOpenKey above. I'm only adding comments for registry keys, not for every possible value under them.
From: "Alexandre Julliard" julliard@winehq.org
They do, the magic comment is on the RegOpenKey above. I'm only adding comments for registry keys, not for every possible value under them.
This is obviously way better then before, but I guess at the end of the day we care about the values. How are we going to keep track of those?
"Dimi Paun" dimi@lattica.com writes:
This is obviously way better then before, but I guess at the end of the day we care about the values. How are we going to keep track of those?
The goal of the comments is to allow to find the relevant pieces of code; once you get there it's fairly easy to determine the values being used. Detailed information about the values and their contents should go in the documentation, the comments are only here to make it easier to check that the documentation is up to date.
From: "Alexandre Julliard" julliard@winehq.org
Detailed information about the values and their contents should go in the documentation, the comments are only here to make it easier to check that the documentation is up to date.
Yeah, agreed. But it would be so much easier to keep the docs up-to-date if we can simply grep for the values. I'm not suggesting that you do the work, but if you think we can mark them somehow for easy grepping, we can add it as a Janitorial task.
"Dimi Paun" dimi@lattica.com writes:
Yeah, agreed. But it would be so much easier to keep the docs up-to-date if we can simply grep for the values. I'm not suggesting that you do the work, but if you think we can mark them somehow for easy grepping, we can add it as a Janitorial task.
It's not the extra work, it's that I'm not convinced we want to add a lot of noise in the source for that. I don't think we can realistically hope to build the documentation only by grepping, we need to check the source anyway.
On Wed, 2005-06-15 at 10:51 +0200, Alexandre Julliard wrote:
It's not the extra work, it's that I'm not convinced we want to add a lot of noise in the source for that. I don't think we can realistically hope to build the documentation only by grepping, we need to check the source anyway.
Well, it's not a matter of building the docs only by grepping, that wouldn't be feasible. But _checking_ if anything has been added or deleted can be done easily. And that would be the important trigger for someone to go in and update the documentation.
Remember that I've tried already to document all the options (we even have a web page for it at http://winehq.org/site/status_options) but it was close to impossible to keep it up-to-date. Just knowing if anything changed would really be invaluable.
As for adding much noise, if we have that many options, we have a lot more problems than the 1-line comments for each of them :)
Dimi Paun dimi@lattica.com writes:
Well, it's not a matter of building the docs only by grepping, that wouldn't be feasible. But _checking_ if anything has been added or deleted can be done easily. And that would be the important trigger for someone to go in and update the documentation.
Yes, but it doesn't really help if the comments are not up to date. I'd prefer to make sure it's dead easy to update the doc directly rather than ask people to maintain comments and then have to come back and sync with the doc. That may mean putting the doc directly in the source, or having a wiki page than everybody can update, I don't know; but I think we should be able to find a better mechanism than these magic comments.
On Wed, 2005-06-15 at 13:25 +0200, Alexandre Julliard wrote:
Yes, but it doesn't really help if the comments are not up to date. I'd prefer to make sure it's dead easy to update the doc directly rather than ask people to maintain comments and then have to come back and sync with the doc. That may mean putting the doc directly in the source, or having a wiki page than everybody can update, I don't know; but I think we should be able to find a better mechanism than these magic comments.
Putting the documentation into the comments may very well be the way to go. But this implies putting a more embellished magic comment in. If you don't want it in the code, at lest we need a pointer/marker. So either way we need an easy to parse/grep comment.
Personally I think that embedding the docs in the documentation is probably the way to go. For code related docs, I think it's the only feasible approach (see how successful Javadoc is).
We can start with a just a marker and a Janitoral task of enhancing the markers with the appropriate markup and documentation. We just need to decide what to do, and document it on the Wiki. I'm sure folks will help out with this if there is a clear direction on where we want to go.
I'd have to agree with you guys on this one. One thing I can think of that I would like to take on (given enough time to do it all) is create a wiki page that I can use to document all of the fixme's, warn's and err's that occur in the source, and then ask anyone that is contributing code to update it when they add/remove one of those. For example, it might be helpful to a user to know that "err:midi:OSS_MidiInit ioctl on midi info for device 0 failed" is more of a fixme than an error, and exactly what that "gibberish" means, so that they dont go reporting it (making a dupe report), etc..
Dustin
Dimi Paun wrote:
On Wed, 2005-06-15 at 13:25 +0200, Alexandre Julliard wrote:
Yes, but it doesn't really help if the comments are not up to date. I'd prefer to make sure it's dead easy to update the doc directly rather than ask people to maintain comments and then have to come back and sync with the doc. That may mean putting the doc directly in the source, or having a wiki page than everybody can update, I don't know; but I think we should be able to find a better mechanism than these magic comments.
Putting the documentation into the comments may very well be the way to go. But this implies putting a more embellished magic comment in. If you don't want it in the code, at lest we need a pointer/marker. So either way we need an easy to parse/grep comment.
Personally I think that embedding the docs in the documentation is probably the way to go. For code related docs, I think it's the only feasible approach (see how successful Javadoc is).
We can start with a just a marker and a Janitoral task of enhancing the markers with the appropriate markup and documentation. We just need to decide what to do, and document it on the Wiki. I'm sure folks will help out with this if there is a clear direction on where we want to go.
-
Alexandre Julliard -
Dimi Paun -
Dustin Navea