I haven't gotten a chance to read the "Writing Guidelines" part yet, but for most part (excluding my comments below), everything up to that point is quite well done. I think it gives a very good and thorough intro to the various commands one might need when writing docs. I like it. :-) On 3/20/07, Ingo Weinhold <bonefish@xxxxxxxxxxxxxxx> wrote:
On 2007-03-19 at 11:04:37 [+0100], Niels Reedijk <niels.reedijk@xxxxxxxxx> wrote: > > I just commited the first draft of the API documentation guidelines, > to start a discussion. Personally I'm very much in favor of inline documentation (though not in the headers for obvious reasons). If for some reason a documentation becomes lengthy I don't have a problem with moving it to a separate file, but in general I'd prefer it to stay with the implementation.
I tend to agree with Ingo. I wasn't going to say anything because I figured the decision to use external files was made while I was AWOL, but as long as he's speaking up, I'll make my points, too. :-) Having the documentation sitting right with the code makes it a lot simpler to find when you need it, more convenient to update, and it makes it more likely that someone who just happens to be working on a function will notice when the documentation is incorrect and fix it. And I'm not sure I agree with most of the reasons given for putting the docs in separate files: "First of all, it would unnecesarily add much cruft to the headers that the compiler will have to parse unneededly. File access and speed isn't BeOS and Haiku's best quality." Please feel free to correct me if I'm wrong, but I thought accessing more files was the significantly slower part, not accessing more data in the same number of files. "The second reason is that the system headers are included throughout the tree. It's a waste of electricity to have everybody recompile the entire tree if someone fixes a typo in the documentation." If you make sure you only put documentation in the source files, not the headers, as Ingo mentioned, then fixing a single typo means everybody will only have to recompile a single file, which really isn't that bad. "Likewise, the reason to not put the documentation in the source is that it unnecesarily clutters up that source." I don't know that "unnecessarily clutters up that source" is really accurate. The "clutter" is in fact documentation for the code next to which it is placed. Clutter implies that you're adding junk that just takes up space, when the reality is you're adding useful information that can be very helpful when working on code in that file. Perhaps it's technically not necessary, but it certainly isn't a negative having more documentation lying within convenient reach. Again, I don't know the history of the decision to use external files for documentation, so if I'm just rehashing something that's already been discussed to death, please feel free to ignore me. :-) -Tyler