hrev53952 adds 1 changeset to branch 'master'
old head: d4dbce2983de47829ad73e8f72ffe203083a04bc
new head: a8081885d2bcc5076d27ea1cbc5b9c0cc60f1126
overview:
https://git.haiku-os.org/haiku/log/?qt=range&q=a8081885d2bc+%5Ed4dbce2983de
----------------------------------------------------------------------------
a8081885d2bc: 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.
[ Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev53952
Commit: a8081885d2bcc5076d27ea1cbc5b9c0cc60f1126
URL: https://git.haiku-os.org/haiku/commit/?id=a8081885d2bc
Author: Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
Date: Sun Mar 8 08:57:37 2020 UTC
----------------------------------------------------------------------------
13 files changed, 101 insertions(+), 80 deletions(-)
docs/user/app/Notification.dox | 4 +-
docs/user/book.css | 5 ++
docs/user/interface/Button.dox | 2 +-
docs/user/interface/Region.dox | 2 +-
docs/user/interface/Screen.dox | 1 -
docs/user/interface/Shape.dox | 5 --
docs/user/locale/TimeFormat.dox | 24 ----------
docs/user/midi2/Midi2Defs.dox | 66 +++++++++++++++++++++++---
docs/user/storage/File.dox | 2 +-
docs/user/storage/MimeType.dox | 1 -
docs/user/support/String.dox | 32 -------------
docs/user/support/SupportDefs.dox | 30 +++++++++++-
docs/user/translation/TranslatorRoster.dox | 7 ++-
----------------------------------------------------------------------------
diff --git a/docs/user/app/Notification.dox b/docs/user/app/Notification.dox
index d6f587caa7..c5f1dfd794 100644
--- a/docs/user/app/Notification.dox
+++ b/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
diff --git a/docs/user/book.css b/docs/user/book.css
index db5289a0f8..05c294844b 100644
--- a/docs/user/book.css
+++ b/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;
diff --git a/docs/user/interface/Button.dox b/docs/user/interface/Button.dox
index bd9b956399..3f9da29993 100644
--- a/docs/user/interface/Button.dox
+++ b/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.
diff --git a/docs/user/interface/Region.dox b/docs/user/interface/Region.dox
index 738fb8a04c..af17dc0dc1 100644
--- a/docs/user/interface/Region.dox
+++ b/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.
diff --git a/docs/user/interface/Screen.dox b/docs/user/interface/Screen.dox
index a13dc6e85a..1b44035acc 100644
--- a/docs/user/interface/Screen.dox
+++ b/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
diff --git a/docs/user/interface/Shape.dox b/docs/user/interface/Shape.dox
index 41a00ff18e..c9ac43bc7a 100644
--- a/docs/user/interface/Shape.dox
+++ b/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
*/
diff --git a/docs/user/locale/TimeFormat.dox b/docs/user/locale/TimeFormat.dox
index 09d00521a0..b22b1bee41 100644
--- a/docs/user/locale/TimeFormat.dox
+++ b/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
diff --git a/docs/user/midi2/Midi2Defs.dox b/docs/user/midi2/Midi2Defs.dox
index 778210ff1e..d82d0ad86c 100644
--- a/docs/user/midi2/Midi2Defs.dox
+++ b/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.
*/
diff --git a/docs/user/storage/File.dox b/docs/user/storage/File.dox
index e4cfd49419..cc84d3648c 100644
--- a/docs/user/storage/File.dox
+++ b/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.
diff --git a/docs/user/storage/MimeType.dox b/docs/user/storage/MimeType.dox
index 2b5e11bc36..bd10e2983d 100644
--- a/docs/user/storage/MimeType.dox
+++ b/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
*/
diff --git a/docs/user/support/String.dox b/docs/user/support/String.dox
index 38f243a724..8594d749b4 100644
--- a/docs/user/support/String.dox
+++ b/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.
diff --git a/docs/user/support/SupportDefs.dox
b/docs/user/support/SupportDefs.dox
index 81c4483f25..88e9ea7fa8 100644
--- a/docs/user/support/SupportDefs.dox
+++ b/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.
*/
diff --git a/docs/user/translation/TranslatorRoster.dox
b/docs/user/translation/TranslatorRoster.dox
index 9d464e72b3..723efe1f1c 100644
--- a/docs/user/translation/TranslatorRoster.dox
+++ b/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
- translator in the roster.
- \retval B_NO_TRANSLATOR \a info was \c NULL and no suitable translator
was
- found.
+ \retval B_NO_TRANSLATOR When \a info was non-null, it did not match to
any
+ translator in the roster. If \a info was \c NULL, then no
suitable
+ translator was 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.
