[openbeos] Re: First draft of the API documentation guidelines

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

Other related posts: