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/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
-	properties from \a font are set on the view.
+	By passing \c B_FONT_ALL to the \a mask parameter as is the default all
+	font properties from \a font are set on the view.
 
-	\param font A pointer to a BFont object to set. Choices include:
-	  - \c be_plain_font
-	  - \c be_bold_font
-	  - \c be_fixed_font
-	\param mask A mask of the following values to determine what font properties
-	            to set:
+	\param font A pointer to a const BFont object to set on the view.
+	\param mask A mask to determine what font properties to set, either pass
+	       in \c B_FONT_ALL to set all font properties or create a mask
+	       containing one or more of the following values 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
 */