Update BView and BStringView docs

... based on Adrien's suggestions.

* Add \warning back to BView::ResizeToPreferred(), add \remark to highlight
  methods only appropriate to use as part of a BLayout.
* Clarify BView::SetFont() method and refer to BFont docs.
* Clarify BStringView::SetText(), Text(), and Draw().
* add field descriptions for BStringView::Instantiate().

docs/user/interface/StringView.dox

@@ -88,9 +88,6 @@
 	\fn BStringView::BStringView(BMessage* archive)
 	\brief Archive constructor.
 
-	The string view's text, alignment, and view flags can be set using this
-	constructor.
-
 	\warning This method is usually not called directly. If you want to build
 	         a string view from an archive message you should call
 	         Instantiate() instead which can handle errors properly.
@@ -121,6 +118,16 @@
 	\fn BArchivable* BStringView::Instantiate(BMessage* archive)
 	\brief Creates a new BStringView object from an \a archive message.
 
+	The string view's text, and alignment can be set using this method.
+	- The "_text" property is a \c B_STRING_TYPE containing the text of
+	  the string view.
+	- The "_align" property is a \c B_INT32_TYPE containing the string
+	  view's alignment flag. This should be casted to an alignment type.
+	  Choices are:
+      - \c B_ALIGN_LEFT
+      - \c B_ALIGN_RIGHT
+      - \c B_ALIGN_CENTER
+
 	\return A newly created BStringView object or \c NULL if the message
 	        doesn't contain an archived BStringView.
 
@@ -196,17 +203,17 @@
 
 /*!
 	\fn void BStringView::Draw(BRect updateRect)
-	\brief Draws the area of the string view that intersects \a updateRect.
+	\brief Draws the area of the view that intersects \a updateRect.
 
-	\note This is an hook method called by the Interface Kit, you don't
+	\remark This is an hook method called by the Interface Kit, you don't have to
-	      have to call it yourself. If you need to forcefully redraw the
+	        call it yourself. If you need to forcefully redraw the view consider
-	      string view consider calling Invalidate() instead.
+	        calling Invalidate() instead.
 
 	\param updateRect The rectangular area to be drawn.
 
-	\sa BView::Draw()
-
 	\since BeOS R3
+
+	\see BView::Draw()
 */
 
 
@@ -332,8 +339,12 @@
 
 /*!
 	\fn void BStringView::SetText(const char* text)
-	\brief Sets the \a text string displayed by the string view. The memory
+	\brief Sets the \a text string displayed by the string view.
-	       used by the old string is freed.
+
+	The \a text string is copied, BStringView does not take ownership
+	of the memory referenced by the pointer so you should free it yourself
+	afterwords. If a string has previously been set on the string view, the
+	memory used by the old string is freed before setting the new string.
 
 	\param text The \a text string to set.
 
@@ -343,9 +354,9 @@
 
 /*!
 	\fn const char* BStringView::Text() const
-	\brief Returns the text currently set to the string view.
+	\brief Returns the text currently set on the string view.
 
-	\returns The text set to the string view.
+	\returns The string view's text as a const char*.
 
 	\since BeOS R3
 */

docs/user/interface/View.dox

@@ -741,7 +741,7 @@ SetViewColor(Parent()->ViewColor());
 	\brief Creates a new BView object from the \a data message.
 
 	\returns A newly created BView object or \c NULL if the message doesn't
-		contain an archived BView.
+	         contain an archived BView.
 
 	\since BeOS R3
 */
@@ -1403,7 +1403,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::Flush() const
 	\brief Flushes the attached window's connection to App Server.
 
-	If the view isn't attached to a window, Flush() does nothing.
+	\note If the view isn't attached to a window, Flush() does nothing.
 
 	\since BeOS R3
 */
@@ -1454,7 +1454,8 @@ SetViewColor(Parent()->ViewColor());
 	\brief Resizes the view to its preferred size keeping the position of the
 	       left top corner constant.
 
-	It is not recommended to use this method for views that are part of a BLayout.
+	\warning It is not recommended to use this method for views that are part
+	         of a BLayout.
 
 	\since BeOS R3
 */
@@ -1502,7 +1503,8 @@ SetViewColor(Parent()->ViewColor());
 		BHandler* replyTo)
 	\brief Initiates a drag-and-drop session.
 
-	This method only works if the BView objects are attached to a window.
+	\warning This method only works if the BView objects are attached to a
+	         window.
 
 	\param message Contains data to be dragged and dropped on the destination
 	       view. The caller retains responsibility for this object.
@@ -1521,7 +1523,8 @@ SetViewColor(Parent()->ViewColor());
 		BPoint offset, BHandler* replyTo)
 	\brief Initiates a drag-and-drop session of an \a image.
 
-	This method only works if the BView objects are attached to a window.
+	\warning This method only works if the BView objects are attached to a
+	         window.
 
 	\param message Contains data to be dragged and dropped on the destination
 	       view. The caller retains responsibility for this object.
@@ -1543,7 +1546,8 @@ SetViewColor(Parent()->ViewColor());
 	\brief Initiates a drag-and-drop session of an \a image with drawing_mode
 	       set by \a dragMode.
 
-	This method only works if the BView objects are attached to a window.
+	\warning This method only works if the BView objects are attached to a
+	         window.
 
 	\param message Contains data to be dragged and dropped on the destination
 	       view. The caller retains responsibility for this object.
@@ -2171,15 +2175,13 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::SetFont(const BFont* font, uint32 mask)
 	\brief Set the font of the view.
 
-	By passing \c B_FONT_ALL to the \a mask parameter as is the default all font
+	By passing \c B_FONT_ALL to the \a mask parameter as is the default all
-	properties from \a font are set on the view.
+	font properties from \a font are set on the view.
 
-	\param font A pointer to a BFont object to set. Choices include:
+	\param font A pointer to a const BFont object to set on the view.
-	  - \c be_plain_font
+	\param mask A mask to determine what font properties to set, either pass
-	  - \c be_bold_font
+	       in \c B_FONT_ALL to set all font properties or create a mask
-	  - \c be_fixed_font
+	       containing one or more of the following values to set:
-	\param mask A mask of the following values to determine what font properties
-	            to set:
 	  - \c B_FONT_FAMILY_AND_STYLE
 	  - \c B_FONT_SPACING
 	  - \c B_FONT_SIZE
@@ -2189,6 +2191,8 @@ SetViewColor(Parent()->ViewColor());
 	  - \c B_FONT_ROTATION
 	  - \c B_FONT_FLAGS
 
+	\see BFont for more details.
+
 	\since BeOS R3
 */
 
@@ -3959,7 +3963,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn BSize BView::MinSize()
 	\brief Return the minimum size of the view.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\return The minimum size of the view as a BSize.
 
@@ -3973,7 +3977,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn BSize BView::MaxSize()
 	\brief Return the maximum size of the view.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\return The maximum size of the view as a BSize.
 
@@ -3987,7 +3991,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn BSize BView::PreferredSize()
 	\brief Return the preferred size of the view.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\return The preferred size of the view as a BSize.
 
@@ -4001,7 +4005,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::SetExplicitMinSize(BSize size)
 	\brief Set this view's min size, to be used by MinSize().
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\sa BAbstractLayout::SetExplicitMinSize()
 
@@ -4013,7 +4017,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::SetExplicitMaxSize(BSize size)
 	\brief Set this view's max size, to be used by MaxSize().
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\sa BAbstractLayout::SetExplicitMaxSize()
 
@@ -4025,7 +4029,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::SetExplicitPreferredSize(BSize size)
 	\brief Set this view's preferred size, to be used by PreferredSize().
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\sa BAbstractLayout::SetExplicitPreferredSize()
 
@@ -4037,7 +4041,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::SetExplicitAlignment(BAlignment alignment)
 	\brief Set this view's alignment, to be used by Alignment().
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\sa BAbstractLayout::SetExplicitAlignment()
 
@@ -4049,8 +4053,6 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::SetLayout(BLayout* layout)
 	\brief Sets the \a layout of the view.
 
-	This is only meaningful if the view is part of a BLayout.
-
 	\param layout The \a layout to set.
 
 	\since Haiku R1
@@ -4061,7 +4063,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn BLayout* BView::GetLayout() const
 	\brief Get the layout of the view.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\returns The layout of the view.
 
@@ -4073,7 +4075,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::InvalidateLayout(bool descendants)
 	\brief Invalidate layout.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\param descendants Also invalidate its children views.
 
@@ -4085,7 +4087,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::EnableLayoutInvalidation()
 	\brief Enable layout invalidation.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\since Haiku R1
 */
@@ -4095,7 +4097,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::DisableLayoutInvalidation()
 	\brief Disable layout invalidation.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\since Haiku R1
 */
@@ -4105,7 +4107,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn bool BView::IsLayoutInvalidationDisabled()
 	\brief Returns whether or not layout invalidation is disabled.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\return \c true of layout invalidation is disabled, \c false otherwise.
 
@@ -4117,7 +4119,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn bool BView::IsLayoutValid() const
 	\brief Returns whether or not the layout is valid.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\brief Returns \c true if the layout is valid, \c false otherwise.
 
@@ -4146,7 +4148,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::Layout(bool force)
 	\brief Layout the view.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\param force If \c true layout even if valid.
 
@@ -4158,7 +4160,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::Relayout()
 	\brief Relayout the view.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\since Haiku R1
 */
@@ -4168,7 +4170,7 @@ SetViewColor(Parent()->ViewColor());
 	\fn void BView::DoLayout()
 	\brief Layout view within the layout context.
 
-	This is only meaningful if the view is part of a BLayout.
+	\remark This is only meaningful if the view is part of a BLayout.
 
 	\since Haiku R1
 */