[haiku-commits] haiku: hrev53952 - in docs/user: midi2 support locale interface translation

  • From: Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
  • To: haiku-commits@xxxxxxxxxxxxx
  • Date: Sun, 8 Mar 2020 05:00:47 -0400 (EDT)

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.


Other related posts:

  • » [haiku-commits] haiku: hrev53952 - in docs/user: midi2 support locale interface translation - Niels Sascha Reedijk