[haiku-commits] Re: r39686 - in haiku/trunk/docs/user: . interface
- From: "Stephan Assmus" <superstippi@xxxxxx>
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Tue, 30 Nov 2010 23:42:31 +0100
Hi,
> I would like to get some careful review for this. Nielx put out the
> (valid) concern that he's not confident in random students with no previous
> Haiku
> experience to write the API reference.
> I'd like to know if I should put online more of these tasks, or if I
> should stop now because the quality is too low.
there are a couple mistakes.
> +/*! \fn BBox::BBox(BRect frame, const char *name = NULL, uint32
> resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP, uint32 flags = B_WILL_DRAW |
> B_FRAME_EVENTS | B_NAVIGABLE_JUMP, border_style border = B_FANCY_BORDER)
> + \brief Constructs a Box from a set of dimensions.
> +
> + This is the only constructor that can be used if the box is to be
> inserted
> + in a window that doesn't use the layout system.
> +
> + \param frame The bounds of the box.
> + \param name The name of the box.
> + \param resizingMode Defines the behavior of the box as the window
> resizes.
Actually: as the parent view resizes. The window size may or may not have
anything to do with it.
[...]
> + You don't usually call this directly, if you want to build a BBox from a
> + message, prefer calling Instanciate, which can properly handle errors.
Spelling: Instantiate.
[...]
> +/*! \fn virtual void BBox::SetBorder(border_style border)
> + \brief Sets the border style.
> +*/
There could be a description of the different border styles.
> +/*! \fn float BBox::TopBorderOffset()
> + \brief Gets the label's distance from the very top of the Box, in
> pixels.
> +*/
I think this is wrong. IIRC, this method returns the offset of the visual
border from the top of the bounds rectangle. The border is drawn center aligned
with the label, thus the offset is smaller than the label height. If you used
to BBox objects side by side, one with a label and one without, you could inset
the top side of the one without a label by this value and have both top borders
visually aligned.
> +/*! \fn const char* BBox::Label() const
> + \brief Gets the label's text.
> +
> + This only works if the label view is a BTextView.
> +*/
Wrong, this just returns the label from SetLabel(const char*), or the label
passed to the constructor. In fact, if you used a BTextView as the label view,
this method would *not* return the text inside the BTextView.
> +/*! \fn virtual void BBox::Draw(BRect updateRect)
> + \brief Draws onto the parent window the part of the box that intersects
> + the dirty area.
> +
> + \param updateRect The area that needs to be redrawn. Note the box may
> draw
> + more than asked.
> +*/
This is a hook method, the user should not call it. "may draw more than
*asked*" somehow implies it could be called by client apps. While most other
method description are pretty brief, this one could just mention that it
renders the box.
> +/*! \fn virtual void BBox::FrameResized(float width, float height)
> + \brief Called when the box needs to change its size.
> +
> + This function may be called either because the window in which the box
> is
> + was resized, or because the window layout was otherwise altered.
> +
> + It recomputes the bounds of the box and makes it redraw itself as
> needed.
> +*/
This is wrong in that FrameResized() is informative. The new size is already a
fact, not calculated in that method.
> +/*! \fn virtual void BBox::ResizeToPreferred()
> + \brief Resizes the box to its preferred dimensions.
> +
> + This only works in the layout system mode.
> +*/
Wrong. It actually works only in non-layouted mode. It's a manual resize, which
should never happen in layouted view hierarchies.
> +/*! virtual void BBox::GetPreferredSize(float* _width, float* _height)
> + \brief Gets the dimensions the box would prefer to be.
> +
> + The size is computed from the children sizes, unless it was explicitly
> set
> + for the box.
This is not quite right. In non-layouted mode, you cannot set an explicit size.
> + \param _width An output parameter. The width of the preferred size is
> placed in here.
> + \param _height An output parameter. The height of the preferred size is
> placed in here.
> +*/
Either param may be NULL.
> +/*! \fn virtual BSize BBox::MinSize()
> + \brief Gets the minimum possible size of the Box.
> +
> + This size ensures the label and all the childs are visible.
> +*/
Could be phrased better. Also, according to another place of the documentation,
there should be only a single child.
> +/*! \fn virtual BSize BBox::MaxSize()
> + \brief Gets the maximum possible size of the Box.
> +
> + The maximum size depends on the children.
> +*/
Plural?
> +/*! \fn virtual BSize BBox::PreferredSize()
> + \brief Returns the box's preferred size.
> +
> + This is the same as GetPreferredSize, but using the more convenient
> BSize
> + struct.
> +*/
> +
> +
> +/*! \fn virtual void BBox::DoLayout()
> + \brief Lays out the box. Moves everything to its appropriate position.
> +
> + This only works if the box uses the layout system, ie., was created with
> + one of the BRect-less constructors.
> +*/
Indeed, but what does it do?
Hope this helps, sorry for not providing better phrases in some places.
Best regards,
-Stephan
Other related posts:
