HaikuBook: fix warnings generated by Doxygen 1.18.16.

This version generates some warnings and identified some problems in our
documentation. It is also a bit more vigilant about undocumented elements, so
these are now decorated with a brief description. In the BNotification docs I
used a stray \p to create some whitespace between code and an image. This is
now fixed in the CSS instead.

docs/user/app/Notification.dox

@@ -83,6 +83,8 @@
 
 /*!
 	\class BNotification
+	\ingroup app
+	\ingroup libbe
 	\brief Construct system-default notifications to be displayed to the user.
 
 	Haiku provides a notification system that allows you to display messages to
@@ -121,8 +123,6 @@
 	notification.Send();
 	\endcode
 
-	\p
-
 	\image html notification_intro.png
 
 	Note that in the previous code example, we set a

docs/user/book.css

@@ -469,6 +469,11 @@ div.contents dt {
 	margin-bottom: 8px;
 }
 
+div.image {
+	margin-top: 16px;
+	margin-bottom: 8px;
+}
+
 .icon {
 	font-weight: bold;
 	font-size: 12px;

docs/user/interface/Button.dox

@@ -530,7 +530,7 @@
 
 
 /*!
-	\fn status_t BControl::SetIcon(const BBitmap* icon, uint32 flags)
+	\fn status_t BButton::SetIcon(const BBitmap* icon, uint32 flags)
 	\brief This convenience method is used to set the bitmaps
 	       for the standard states from a single bitmap.
 

docs/user/interface/Region.dox

@@ -187,7 +187,7 @@
 
 
 /*!
-	fn clipping_rect BRegion::RectAtInt(int32 index)
+	\fn clipping_rect BRegion::RectAtInt(int32 index)
 	\brief Returns the clipping_rect contained in the region at the given
 	       \a index.
 

docs/user/interface/Screen.dox

@@ -452,7 +452,6 @@
 	       available display modes.
 
 	\retval B_OK if the operation was successful.
-	\retval B_ERROR if \a modeList or \a count is invalid.
 	\retval B_ERROR for all other errors.
 
 	\since BeOS R5

docs/user/interface/Shape.dox

@@ -447,11 +447,6 @@
 	\retval B_OK The operation was added successfully.
 	\retval B_NO_MEMORY Ran out of memory while trying to add the operation.
 
-	\return Returns a status code, \c B_OK on success or an error code
-	        otherwise.
-	\retval B_OK The operation was added successfully.
-	\retval B_NO_MEMORY Ran out of memory while trying to add the operation.
-
 	\since BeOS R4
 */
 

docs/user/locale/TimeFormat.dox

@@ -88,30 +88,6 @@
 */
 
 
-/*!
-	\fn status_t BTimeFormat::Format(char* string, size_t maxSize,
-		time_t time, BTimeFormatStyle style) const
-	\brief Fills in \a string with a formatted time for the given
-	       \a time, and \a style for the locale.
-
-	\param string The string buffer to fill with the formatted time.
-	\param time The time (in seconds since midnight) to format.
-	\param style Specify the long format or the short format.
-
-	\returns A status code.
-	\retval B_OK Everything went fine.
-	\retval B_ERROR Unable to lock the BLocale.
-	\retval B_NO_MEMORY Ran out of memory while creating the object.
-
-	\sa BLocale::FormatDate(BString*, time_t, BTimeFormatStyle,
-		const BTimeZone*) const
-	\sa BLocale::FormatDateTime(BString*, time_t, BTimeFormatStyle,
-		BTimeFormatStyle, const BTimeZone*) const
-
-	\since Haiku R1
-*/
-
-
 /*!
 	\fn status_t BTimeFormat::Format(BString& string, const time_t time,
 		const BTimeFormatStyle style, const BTimeZone* timeZone) const

docs/user/midi2/Midi2Defs.dox

@@ -1,13 +1,13 @@
 /*!
 	\file Midi2Defs.h
 	\ingroup midi2
-	\brief Some definitions to define raw MIDI events.
+	\brief Some definitions to define Identifier of MIDI events.
 */
 
 
 /*!
 	\name Channel Message Masks
-	\brief Some definitions to define the raw MIDI events.
+	\brief Some definitions to define the Identifier of MIDI events.
 
 	The default implementation of BMidiLocalConsumer::Data() uses these
 	constants to determine which event has been passed on. If you override
@@ -20,36 +20,43 @@
 
 /*!
 	\var B_NOTE_OFF
+	\brief Identifier of note off message.
 */
 
 
 /*!
 	\var B_NOTE_ON
+	\brief Identifier of note on message.
 */
 
 
 /*!
 	\var B_KEY_PRESSURE
+	\brief Identifier of key pressure message.
 */
 
 
 /*!
 	\var B_CONTROL_CHANGE
+	\brief Identifier of control change message.
 */
 
 
 /*!
 	\var B_PROGRAM_CHANGE
+	\brief Identifier of program change message.
 */
 
 
 /*!
 	\var B_CHANNEL_PRESSURE
+	\brief Identifier of channel pressure message.
 */
 
 
 /*!
 	\var B_PITCH_BEND
+	\brief Identifier of pitch bend message.
 */
 
 
@@ -58,7 +65,7 @@
 
 /*!
 	\name System Messages
-	\brief Some definitions to define the raw MIDI system messages.
+	\brief Some definitions to define the Identifier of MIDI system messages.
 
 	The default implementation of BMidiLocalConsumer::Data() uses these
 	constants to determine which event system message has been passed on.
@@ -73,66 +80,79 @@
 
 /*!
 	\var B_SYS_EX_START
+	\brief Identifier of system exclusive start message.
 */
 
 
 /*!
 	\var B_MIDI_TIME_CODE
+	\brief Identifier of midi time code message.
 */
 
 
 /*!
 	\var B_SONG_POSITION
+	\brief Identifier of song position message.
 */
 
 
 /*!
 	\var B_SONG_SELECT
+	\brief Identifier of song select message.
 */
 
 
 /*!
 	\var B_CABLE_MESSAGE
+	\brief Identifier of cable message.
 */
 
 
 /*!
 	\var B_TUNE_REQUEST
+	\brief Identifier of tune request message.
 */
 
 
 /*!
 	\var B_SYS_EX_END
+	\brief Identifier of system exclusive end message.
 */
 
 
 /*!
 	\var B_TIMING_CLOCK
+	\brief Identifier of timing clock message.
 */
 
 
 /*!
 	\var B_START
+	\brief Identifier of start message.
 */
 
 
 /*!
 	\var B_CONTINUE
+	\brief Identifier of continue message.
 */
 
 
 /*!
 	\var B_STOP
+	\brief Identifier of stop message.
 */
 
 
 /*!
 	\var B_ACTIVE_SENSING
+	\brief Identifier of active sensing message.
 */
 
 
 /*!
 	\var B_SYSTEM_RESET
+	\brief Identifier of system reset message.
 */
 
 
@@ -152,191 +172,225 @@
 //! @{
 
 
-*/
-
-
 /*!
 	\var B_MODULATION
+	\brief Identifier of modulation message.
 */
 
 
 /*!
 	\var B_BREATH_CONTROLLER
+	\brief Identifier of breath controller message.
 */
 
 
 /*!
 	\var B_FOOT_CONTROLLER
+	\brief Identifier of foot controller message.
 */
 
 
 /*!
 	\var B_PORTAMENTO_TIME
+	\brief Identifier of portamento time message.
 */
 
 
 /*!
 	\var B_DATA_ENTRY
+	\brief Identifier of data entry message.
 */
 
 
 /*!
 	\var B_MAIN_VOLUME
+	\brief Identifier of main volume message.
 */
 
 
 /*!
 	\var B_MIDI_BALANCE
+	\brief Identifier of MIDI balance message.
 */
 
 
 /*!
 	\var B_PAN
+	\brief Identifier of pan message.
 */
 
 
 /*!
 	\var B_EXPRESSION_CTRL
+	\brief Identifier of expression control message.
 */
 
 
 /*!
 	\var B_GENERAL_CTRL_1
+	\brief Identifier of general control 1 message.
 */
 
 
 /*!
 	\var B_GENERAL_CTRL_2
+	\brief Identifier of general control 2 message.
 */
 
 
 /*!
 	\var B_GENERAL_CTRL_3
+	\brief Identifier of general control 3 message.
 */
 
 
 /*!
 	\var B_GENERAL_CTRL_4
+	\brief Identifier of general control 4 message.
 */
 
 
 /*!
 	\var B_SUSTAIN_PEDAL
+	\brief Identifier of sustain pedal message.
 */
 
 
 /*!
 	\var B_PORTAMENTO
+	\brief Identifier of portamento message.
 */
 
 
 /*!
 	\var B_SOSTENUTO
+	\brief Identifier of sostenuto message.
 */
 
 
 /*!
 	\var B_SOFT_PEDAL
+	\brief Identifier of soft pedal message.
 */
 
 
 /*!
 	\var B_HOLD_2
+	\brief Identifier of hold 2 message.
 */
 
 
 /*!
 	\var B_GENERAL_CTRL_5
+	\brief Identifier of general control 5 message.
 */
 
 
 /*!
 	\var B_GENERAL_CTRL_6
+	\brief Identifier of general control 6 message.
 */
 
 
 /*!
 	\var B_TEMPO_CHANGE
+	\brief Identifier of tempo change message.
 */
 
 
 /*!
 	\var B_GENERAL_CTRL_7
+	\brief Identifier of general control 7 message.
 */
 
 
 /*!
 	\var B_GENERAL_CTRL_8
+	\brief Identifier of general control 8 message.
 */
 
 
 /*!
 	\var B_EFFECTS_DEPTH
+	\brief Identifier of effects depth message.
 */
 
 
 /*!
 	\var B_TREMOLO_DEPTH
+	\brief Identifier of tremelo depth message.
 */
 
 
 /*!
 	\var B_CHORUS_DEPTH
+	\brief Identifier of chorus depth message.
 */
 
 
 /*!
 	\var B_CELESTE_DEPTH
+	\brief Identifier of celeste depth message.
 */
 
 
 /*!
 	\var B_PHASER_DEPTH
+	\brief Identifier of phaser depth message.
 */
 
 
 /*!
 	\var B_DATA_INCREMENT
+	\brief Identifier of data increment message.
 */
 
 
 /*!
 	\var B_DATA_DECREMENT
+	\brief Identifier of data decrement message.
 */
 
 
 /*!
 	\var B_RESET_ALL_CONTROLLERS
+	\brief Identifier of reset all controllers message.
 */
 
 
 /*!
 	\var B_LOCAL_CONTROL
+	\brief Identifier of local control message.
 */
 
 
 /*!
 	\var B_ALL_NOTES_OFF
+	\brief Identifier of all notes off message.
 */
 
 
 /*!
 	\var B_OMNI_MODE_OFF
+	\brief Identifier of omni mode off message.
 */
 
 
 /*!
 	\var B_OMNI_MODE_ON
+	\brief Identifier of omni mode on message.
 */
 
 
 /*!
 	\var B_MONO_MODE_ON
+	\brief Identifier of mono mode on message.
 */
 
 
 /*!
 	\var B_POLY_MODE_ON
+	\brief Identifier of poly mode on message.
 */
 
 

docs/user/storage/File.dox

@@ -280,7 +280,7 @@
 
 
 /*!
-	ssize_t BFile::Read(void* buffer, size_t size)
+	\fn ssize_t BFile::Read(void* buffer, size_t size)
 	\brief Reads a number of bytes from the file into a buffer.
 
 	\param buffer The buffer the data from the file shall be written to.

docs/user/storage/MimeType.dox

@@ -906,7 +906,6 @@
 	\retval B_OK The ref was retrieved successfully.
 	\retval B_NO_INIT BMimeType was uninitialized.
 	\retval B_BAD_VALUE \a ref was \c NULL.
-	\retval B_NO_INIT BMimeType was uninitialized.
 
 	\since BeOS R3
 */

docs/user/support/String.dox

@@ -636,18 +636,6 @@
 */
 
 
-/*!
-	\fn BString& BString::operator+=(const BString& string)
-	\brief Append the given \a string to the end of the BString.
-
-	\param string The string to append.
-
-	\return This method always returns \c *this.
-
-	\sa Append(const BString&, int32)
-*/
-
-
 /*!
 	\fn BString& BString::Append(const BString& string)
 	\brief Append the given \a string to the end of the BString.
@@ -1998,8 +1986,6 @@
 	\fn int32 BString::IFindFirst(const char* string) const
 	\brief Find the first occurrence of the given \a string case-insensitively.
 
-	\param string The \a string to search for.
-
 	\copydetails FindFirst(const char*) const
 */
 
@@ -2582,24 +2568,6 @@
 //! @{
 
 
-/*!
-	\fn char& BString::operator[](int32 index)
-	\brief Return a reference to the data at the given offset.
-
-	This function can be used to read a byte.
-	There is no bounds checking though, so make sure the \c index
-	you supply is valid.
-
-	\param index The index (zero-based) of the byte to get.
-
-	\return Returns a reference to the specified byte.
-
-	\sa ByteAt(int32 index) for a safer version.
-
-	\since BeOS R5
-*/
-
-
 /*!
 	\fn char BString::operator[](int32 index) const
 	\brief Returns the character in the string at the given offset.

docs/user/support/SupportDefs.dox

@@ -29,41 +29,49 @@
 
 /*!
 	\typedef typedef __haiku_int8 int8
+	\brief 1-byte signed integer.
 */
 
 
 /*!
 	\typedef typedef __haiku_uint8 uint8
+	\brief 1-byte unsigned integer.
 */
 
 
 /*!
 	\typedef typedef __haiku_int16 int16
+	\brief 2-bytes signed integer.
 */
 
 
 /*!
 	\typedef typedef __haiku_uint16 uint16
+	\brief 2-bytes unsigned integer.
 */
 
 
 /*!
 	\typedef typedef __haiku_int32 int32
+	\brief 4-bytes signed integer.
 */
 
 
 /*!
 	\typedef typedef __haiku_uint32 uint32
+	\brief 4-bytes unsigned integer.
 */
 
 
 /*!
 	\typedef typedef __haiku_int64 int64
+	\brief 8-bytes signed integer.
 */
 
 
 /*!
 	\typedef typedef __haiku_uint64 uint64
+	\brief 8-bytes unsigned integer.
 */
 
 
@@ -80,41 +88,49 @@
 
 /*!
 	\typedef typedef volatile int8 vint8
+	\brief 1-byte volatile signed integer.
 */
 
 
 /*!
 	\typedef typedef volatile uint8 vuint8
+	\brief 1-byte volatile unsigned integer.
 */
 
 
 /*!
 	\typedef typedef volatile int16 vint16
+	\brief 2-bytes volatile signed integer.
 */
 
 
 /*!
 	\typedef typedef volatile uint16 vuint16
+	\brief 2-bytes volatile unsigned integer.
 */
 
 
 /*!
 	\typedef typedef volatile int32 vint32
+	\brief 4-bytes volatile signed integer.
 */
 
 
 /*!
 	\typedef typedef volatile uint32 vuint32
+	\brief 4-bytes volatile unsigned integer.
 */
 
 
 /*!
 	\typedef typedef volatile int64 vint64
+	\brief 8-bytes volatile signed integer.
 */
 
 
 /*!
 	\typedef typedef volatile uint64 vuint64
+	\brief 8-bytes volatile unsigned integer.
 */
 
 
@@ -131,41 +147,49 @@
 
 /*!
 	\typedef typedef volatile long vlong
+	\brief Volatile signed long.
 */
 
 
 /*!
 	\typedef typedef volatile int vint
+	\brief Volatile signed int.
 */
 
 
 /*!
 	\typedef typedef volatile short vshort
+	\brief Volatile signed short.
 */
 
 
 /*!
 	\typedef typedef volatile char vchar
+	\brief Volatile signed char.
 */
 
 
 /*!
 	\typedef typedef volatile unsigned long vulong
+	\brief Volatile unsigned long.
 */
 
 
 /*!
 	\typedef typedef volatile unsigned int vuint
+	\brief Volatile unsigned int.
 */
 
 
 /*!
 	\typedef typedef volatile unsigned short vushort
+	\brief Volatile unsigned short.
 */
 
 
 /*!
 	\typedef typedef volatile unsigned char vuchar
+	\brief Volatile unsigned char.
 */
 
 
@@ -181,12 +205,14 @@
 
 
 /*!
-  \typedef typedef unsigned char uchar
+	\typedef typedef unsigned char uchar
+	\brief Unsigned 1-byte wide character.
 */
 
 
 /*!
-  \typedef typedef unsigned short unichar
+	\typedef typedef unsigned short unichar
+	\brief Unsigned 2-byte wide character.
 */
 
 

docs/user/translation/TranslatorRoster.dox

@@ -430,10 +430,9 @@
 
 	\retval B_OK The translated data was successfully written to
 		\a destination.
-	\retval B_NO_TRANSLATOR \a info was non-null but did not match to any
+	\retval B_NO_TRANSLATOR When \a info was non-null, it did not match to any
-		translator in the roster.
+		translator in the roster. If \a info was \c NULL, then no suitable
-	\retval B_NO_TRANSLATOR \a info was \c NULL and no suitable translator was
+		translator was found.
-		found.
 	\retval B_ERROR An error occurred.
 	\retval B_BAD_VALUE \a source or \a destination was \c NULL or
 		\a ioExtension was \c NULL or contained bad data.