[haiku-development] Re: BGroupLayout documentation inconsisency

  • From: Stephan Aßmus <superstippi@xxxxxx>
  • To: haiku-development@xxxxxxxxxxxxx
  • Date: Fri, 20 May 2011 15:31:57 +0200


Am 20.05.2011 17:04, schrieb John Scipione:
I am going through the Haiku Book Documentation and I found an
inconsistency between the code of the BGroupLayout constructor and the
documentation of the constructor and I am not sure which one is right
but I suspect that the code is wrong.

The code in src/kits/interface/GroupLayout.cpp looks like this:

BGroupLayout::BGroupLayout(enum orientation orientation, float spacing)

And the documentation in docs/user/interface/GroupLayout.dox looks like

     \fn BGroupLayout::BGroupLayout(enum orientation, float spacing)
     \brief Creates a new BGroupLayout.
     \param orientation The orientation of this BGroupLayout.
     \param spacing The spacing between BLayoutItems in this BGroupLayout.

Here is the link to the documentation for the BGroupLayout
constructor in the Haiku Book:


As you can see that the word orientation is repeated in the constructor
code. To me this seems erroneous but I am not familiar enough with the
Layout Kit or C++ to know if this is an error or if it has some meaning.
It looks screwed up in the documentation too with the repeated
orientation variable showing up in the wrong column. Perhaps doxygen
doesn't understand this either.

Can someone with a working knowledge of the Layout Kit (Ingo?) please
respond on this.

The code is correct. The problem here is that Be called the type just "orientation", which pollutes the global namespace. According to many Haiku developers, it should have been something else indicating this is an OS API type, like "BOrientation" for example.

In order to be able to name the variable "orientation", like it ought to be named, the code prepends an "enum" to "orientation", so the type is "enum orientation" and the variable name "orientation". Just "orientation orientation" would throw the compiler off, but something like "orientation o" (like in some Be headers) or "orientation direction" would be lame. Doxygen obviously doesn't handle it correctly, it should display the second "orientation" as the variable name.

Best regards,

Other related posts: