[haiku-commits] Re: haiku: hrev45080 - headers/os/media
- From: John Scipione <jscipione@xxxxxxxxx>
- To: "haiku-commits@xxxxxxxxxxxxx" <haiku-commits@xxxxxxxxxxxxx>
- Date: Mon, 24 Dec 2012 18:18:42 -0500
On Mon, Dec 24, 2012 at 5:31 PM, Ingo Weinhold <ingo_weinhold@xxxxxx> wrote:
> On 12/24/2012 11:03 PM, John Scipione wrote:
>>
>> I'd prefer to use the parameter names found in the BeBook unless there
>> is a good reason to change them as it makes writing documentation
>> easier.
>
> Does it? How?
Same reason that it makes writing the code easier I'd imagine, the
BeBook is the only reference we have for how a lot of things work. If
the variable names are the same you can compare them 1:1, if not it
takes a bit more thought. Also the variable names in the BeBook tend
to follow a consistent pattern (for the most part). Most of the time
the differences between the code and the BeBook are minor changes in
language. For instance when I documented BDragger the author used
bounds instead of frame and resizeMask instead of resizingMode. The
BeBook was consistent here, we were inconsistent.
A big reason that I like to copy the variable names in the BeBook is
that in the header uses one name while the cpp file uses a different
name for a variable. This screws up Doxygen because I copy the method
signature from the cpp file into the dox file (as we don't document in
the cpp file directly) and since the header uses a different variable
name Doxygen spits out a warning blahblah parameter undocumented.
I'm not really sure what motivates the author to use different
variable names but my guess is that the header files got copied from
BeOS (since they were publicly available) and then the cpp files were
written from scratch, perhaps by a different person, and that person
used a different variable name in the cpp file but didn't bother to
update the header file. Regardless of what the cause is, I need to fix
it to remove the warning in Doxygen, and to do that I need to know
which is "correct", the header file or the cpp file, and to make this
decision I use the BeBook as the authoritative source.
This case was different, the author of BFileInterface intentionally
changed to using a new style for out parameters and there was no
implementation of these methods. That's fine, but the general rule of
"do it like the BeBook unless you've got a good reason not to" stands
IMHO. I'm bound to find more of these types of problems as I continue
to document the rest of the API.
> Ideally, to avoid potential copyright issues, one shouldn't even look at the
> BeBook when writing documentation.
Well, ideally we should take a clean room approach. The guy writing
the documentation must have never even looked at the BeBook. However,
the ideal case is overkill here since the threat of litigation is low.
Copying the BeBook word for word is a no-no. It is helpful to
reference the BeBook to make sure that the docs are not copied
word-for-word as I've seen that in a couple of places and had to
rewrite those parts.
> PS: I wonder, if Access would be willing to sell the rights to the BeBook
> for a small (or token) amount. The CC BY-NC-ND license is OK for a while,
> but in the long run it is useless to us, since we'd have to rewrite the
> whole thing anyway. While we have already rewritten quite a bit, there's
> still a lot missing and having to do that when there is documentation that
> would only have to be updated is just such a waste of previous time.
That would be great but Access has already been pretty generous
allowing us to distribute the BeBook with a non-derivative CC license
already. Rewriting all the class documentation from the BeBook is a
lot of thankless work, and we are going to lose a lot in the process
but I don't see any other choice.
Other related posts:
