From a8081885d2bcc5076d27ea1cbc5b9c0cc60f1126 Mon Sep 17 00:00:00 2001 From: Niels Sascha Reedijk Date: Sun, 8 Mar 2020 08:57:37 +0000 Subject: [PATCH] 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 | 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 +-- 13 files changed, 101 insertions(+), 80 deletions(-) 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.