From 19a1dd49cff7ec6a6467cbe2f7006b88931c37d8 Mon Sep 17 00:00:00 2001 From: John Scipione Date: Tue, 8 Sep 2020 22:06:24 -0400 Subject: [PATCH] API docs: update TypeConstants.h documentation Most of these say Haiku R1 but were introduced in BeOS R3 or R5. Add documentation for a bunch of missing types. Some minor updates to BMessage docs. Change-Id: Ic6ad1439bd280ab8bc641a6e5c99b93ead512cbc Reviewed-on: https://review.haiku-os.org/c/haiku/+/3199 Reviewed-by: Adrien Destugues --- docs/user/app/Message.dox | 80 +++--- docs/user/support/TypeConstants.dox | 362 ++++++++++++++++++++-------- 2 files changed, 309 insertions(+), 133 deletions(-) diff --git a/docs/user/app/Message.dox b/docs/user/app/Message.dox index cb97649b92..21a16555a9 100644 --- a/docs/user/app/Message.dox +++ b/docs/user/app/Message.dox @@ -1345,8 +1345,7 @@ /*! \fn status_t BMessage::AddRef(const char* name, const entry_ref* ref) - \brief Convenience method to add an \c entry_ref to the label - \a name. + \brief Convenience method to add an \c entry_ref to the label \a name. This method calls AddData() with the \c B_REF_TYPE \a type. @@ -4423,7 +4422,8 @@ bool enabled = GetBool("enabled", false); /*! - \fn rgb_color BMessage::GetColor(const char* name, rgb_color defaultValue) const + \fn rgb_color BMessage::GetColor(const char* name, + rgb_color defaultValue) const \brief Return the rgb_color value from message with \a name, or \a defaultValue if not found. @@ -4440,8 +4440,8 @@ bool enabled = GetBool("enabled", false); /*! \fn rgb_color BMessage::GetColor(const char* name, int32 index, rgb_color defaultValue) const - \brief Return the rgb_color value from message with \a name and \a index, or - \a defaultValue if not found. + \brief Return the rgb_color value from message with \a name and \a index, + or \a defaultValue if not found. \param name The name of the item to retrieve. \param index The index of the item to retrieve if there is more than one. @@ -4554,7 +4554,8 @@ bool enabled = GetBool("enabled", false); /*! - \fn BRect BMessage::GetRect(const char* name, const BRect& defaultValue) const + \fn BRect BMessage::GetRect(const char* name, + const BRect& defaultValue) const \brief Return the BRect object from message with \a name, or \a defaultValue if not found. @@ -4686,7 +4687,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceBool(const char*, bool) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4703,7 +4704,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceInt8(const char*, int8) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4720,7 +4721,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceUInt8(const char*, uint8) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4737,7 +4738,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceInt16(const char*, int16) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4750,11 +4751,11 @@ bool enabled = GetBool("enabled", false); \param name The name of the item. \param value The value to set the item to. - This function calls AddUInt16(const char*, uint16) in case the item does not - exist yet, and ReplaceUInt16(const char*, uint16) in case it does. + This function calls AddUInt16(const char*, uint16) in case the item does + not exist yet, and ReplaceUInt16(const char*, uint16) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4771,7 +4772,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceInt32(const char*, int32) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4788,7 +4789,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceUInt32(const char*, uint32) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4805,7 +4806,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceInt64(const char*, int64) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4818,11 +4819,11 @@ bool enabled = GetBool("enabled", false); \param name The name of the item. \param value The value to set the item to. - This function calls AddUInt64(const char*, uint64) in case the item does not - exist yet, and ReplaceUInt64(const char*, uint64) in case it does. + This function calls AddUInt64(const char*, uint64) in case the item does + not exist yet, and ReplaceUInt64(const char*, uint64) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4835,11 +4836,11 @@ bool enabled = GetBool("enabled", false); \param name The name of the item. \param value The value to set the item to. - This function calls AddColor(const char*, rgb_color) in case the item does not - exist yet, and ReplaceColor(const char*, rgb_color) in case it does. + This function calls AddColor(const char*, rgb_color) in case the item does + not exist yet, and ReplaceColor(const char*, rgb_color) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4852,11 +4853,12 @@ bool enabled = GetBool("enabled", false); \param name The name of the item. \param value The value to set the item to. - This function calls AddPointer(const char*, const void*) in case the item does not - exist yet, and ReplacePointer(const char*, const void*) in case it does. + This function calls AddPointer(const char*, const void*) in case the item + does not exist yet, and ReplacePointer(const char*, const void*) in case + it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4869,11 +4871,12 @@ bool enabled = GetBool("enabled", false); \param name The name of the item. \param string The value to set the item to. - This function calls AddString(const char*, const char*) in case the item does not - exist yet, and ReplaceString(const char*, const char*) in case it does. + This function calls AddString(const char*, const char*) in case the item + does not exist yet, and ReplaceString(const char*, const char*) in case + it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4886,11 +4889,12 @@ bool enabled = GetBool("enabled", false); \param name The name of the item. \param string The value to set the item to. - This function calls AddString(const char*, const BString&) in case the item does not - exist yet, and ReplaceString(const char*, const BString&) in case it does. + This function calls AddString(const char*, const BString&) in case the item + does not exist yet, and ReplaceString(const char*, const BString&) in case + it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4907,7 +4911,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceFloat(const char*, float) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4924,7 +4928,7 @@ bool enabled = GetBool("enabled", false); exist yet, and ReplaceDouble(const char*, double) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4943,7 +4947,7 @@ bool enabled = GetBool("enabled", false); ReplaceAlignment(const char*, const BAlignment &) in case it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4961,7 +4965,7 @@ bool enabled = GetBool("enabled", false); it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4979,7 +4983,7 @@ bool enabled = GetBool("enabled", false); it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -4997,7 +5001,7 @@ bool enabled = GetBool("enabled", false); it does. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ @@ -5012,7 +5016,7 @@ bool enabled = GetBool("enabled", false); This method is used internally. Use the Set* methods above. \returns A status code, \c B_OK in case of success and \c B_BAD_TYPE in - case the item already exists with a different data type. + case the item already exists with a different data type. \since Haiku R1 */ diff --git a/docs/user/support/TypeConstants.dox b/docs/user/support/TypeConstants.dox index b73e4aba42..2d776240da 100644 --- a/docs/user/support/TypeConstants.dox +++ b/docs/user/support/TypeConstants.dox @@ -1,5 +1,5 @@ /* - * Copyright 2007-2014 Haiku, Inc. All rights reserved. + * Copyright 2007-2020 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -7,7 +7,7 @@ * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/support/TypeConstants.h rev 43506 + * headers/os/support/TypeConstants.h hrev54549 */ @@ -15,20 +15,20 @@ \file TypeConstants.h \ingroup support \ingroup libbe - \brief Represents type codes that are used in various part of the Haiku API. + \brief Represents type codes that are used by parts of the Haiku API. - The type codes all refer to a specified type, except one. B_ANY_TYPE can - refer to literally any type. This type could be used in case you send or receive - data of which you don't know the type, but you want to send or receive it - anyway. + The type codes all refer to a specified type, except one: \c B_ANY_TYPE + can refer to literally any type. This type could be used in case you send + or receive data of which you don't know the type, but you want to send or + receive it anyway. */ /*! \var B_ANY_TYPE - \brief General type when the exact contents is not yet known. + \brief General type when the exact contents are not yet known. - \since Haiku R1 + \since BeOS R3 */ @@ -56,7 +56,7 @@ \var B_BOOL_TYPE \brief Boolean value. - \since Haiku R1 + \since BeOS R3 */ @@ -64,63 +64,7 @@ \var B_CHAR_TYPE \brief Represents the \c char type. - \since Haiku R1 -*/ - - -/*! - \var B_COLOR_8_BIT_TYPE - \brief Represents a one-byte color. - - \since Haiku R1 -*/ - - -/*! - \var B_DOUBLE_TYPE - \brief Represents the \c double type. - - \since Haiku R1 -*/ - - -/*! - \var B_FLOAT_TYPE - \brief Represents the \c float type. - - \since Haiku R1 -*/ - - -/*! - \var B_GRAYSCALE_8_BIT_TYPE - \brief Represents a byte-long grayscale value. - - \since Haiku R1 -*/ - - -/*! - \var B_INT16_TYPE - \brief Represents a \c short type. - - \since Haiku R1 -*/ - - -/*! - \var B_INT32_TYPE - \brief Represents a \c long type. - - \since Haiku R1 -*/ - - -/*! - \var B_INT64_TYPE - \brief Represents a \c long \c long type. - - \since Haiku R1 + \since BeOS R3 */ @@ -128,45 +72,125 @@ \var B_INT8_TYPE \brief Represents a \c char type used for integer storage. - \since Haiku R1 + \since BeOS R3 */ /*! - \var B_LARGE_ICON_TYPE - \brief Represents a large icon. + \var B_INT16_TYPE + \brief Represents a \c short type. - \since Haiku R1 + \since BeOS R3 */ /*! - \var B_MEDIA_PARAMETER_GROUP_TYPE - \brief Represents the BParameterGroup type from the media kit. + \var B_INT32_TYPE + \brief Represents a \c long type. - \since Haiku R1 + \since BeOS R3 */ /*! - \var B_MEDIA_PARAMETER_TYPE - \brief Represents the BParameter type from the media kit. + \var B_INT64_TYPE + \brief Represents a \c long \c long type. - \since Haiku R1 + \since BeOS R3 */ /*! - \var B_MEDIA_PARAMETER_WEB_TYPE - \brief Represents the BParameterWeb type from the media kit. + \var B_UINT8_TYPE + \brief Represents an unsigned \c char type used for integer storage. - \since Haiku R1 + \since BeOS R3 +*/ + + +/*! + \var B_UINT16_TYPE + \brief Represents an unsigned \c short type. + + \since BeOS R3 +*/ + + +/*! + \var B_UINT32_TYPE + \brief Represents an unsigned \c long type. + + \since BeOS R3 +*/ + + +/*! + \var B_UINT64_TYPE + \brief Represents an unsigned \c long \c long type. + + \since BeOS R3 +*/ + + +/*! + \var B_FLOAT_TYPE + \brief Represents the \c float type. + + \since BeOS R3 +*/ + + +/*! + \var B_DOUBLE_TYPE + \brief Represents the \c double type. + + \since BeOS R3 +*/ + + +/*! + \var B_OFF_T_TYPE + \brief Represents the \c off_t type. + + \since BeOS R3 +*/ + + +/*! + \var B_SIZE_T_TYPE + \brief Represents the unsigned \c size_t type. + + \since BeOS R3 +*/ + + +/*! + \var B_SSIZE_T_TYPE + \brief Represents the signed \c ssize_t type. + + \since BeOS R3 +*/ + + +/*! + \var B_POINTER_TYPE + \brief Represents a pointer type, including \c void*. + + \since BeOS R3 +*/ + + +/*! + \var B_OBJECT_TYPE + \brief Represents an object pointer type such as BMessage*. + + \since BeOS R3 */ /*! \var B_MESSAGE_TYPE - \brief Represents a BMessage type. + \brief Represents a BMessage object. \since Haiku R1 */ @@ -174,13 +198,161 @@ /*! \var B_MESSENGER_TYPE - \brief Represents a BMessenger type. + \brief Represents a BMessenger object. + + \since BeOS R3 +*/ + + +/*! + \var B_RECT_TYPE + \brief Represents a BRect object. + + \since BeOS R3 +*/ + + +/*! + \var B_REF_TYPE + \brief Represents an entry_ref structure. + + \since BeOS R3 +*/ + + +/*! + \var B_RGB_COLOR_TYPE + \brief Represents an \c rgb_color structure. + + \since BeOS R3 +*/ + + +/*! + \var B_PATTERN_TYPE + \brief Represents a \c pattern structure. + + \since BeOS R3 +*/ + + +/*! + \var B_ASCII_TYPE + \brief Represents a text string in ASCII format. + + \warning Deprecated, do not use, use \c B_STRING_TYPE instead. + + \since BeOS R3 +*/ + + +/*! + \var B_STRING_TYPE + \brief Represents a \c NUL terminated character array. + + \since BeOS R3 +*/ + + +/*! + \var B_MONOCHROME_1_BIT_TYPE + \brief Represents raw bitmap data in the \c B_MONOCHROME_1_BIT color space + (1 bit per pixel.) + + \since BeOS R3 +*/ + + +/*! + \var B_GRAYSCALE_8_BIT_TYPE + \brief Represents bitmap data in the \c B_GRAYSCALE_8_BIT color space + (8-bits per pixel.) + + \since BeOS R3 +*/ + + +/*! + \var B_COLOR_8_BIT_TYPE + \brief Represents raw bitmap data in the \c B_COLOR_8_BIT color space + (8-bits per pixel.) + + \since BeOS R3 +*/ + + +/*! + \var B_RGB_32_BIT_TYPE + \brief Represents raw bitmap data in the \c B_RGB_32_BIT color space + (32-bits per pixel.) + + \since BeOS R3 +*/ + + +/*! + \var B_TIME_TYPE + \brief Represents 32-bit \c time_t data on 32-bit or 64-bit \c time_t data + on 64-bit. + + \since BeOS R3 +*/ + + +/*! + \var B_RAW_TYPE + \brief Represents untyped raw data, a stream of bytes. + + \since BeOS R3 +*/ + + +/*! + \var B_MIME_TYPE + \brief Represents a MIME string of the data type. + + \since BeOS R3 +*/ + + +/*! + \var B_MEDIA_PARAMETER_TYPE + \brief Represents the BParameter type from the media kit. + + \since BeOS R5 +*/ + + +/*! + \var B_MEDIA_PARAMETER_WEB_TYPE + \brief Represents the BParameterWeb type from the media kit. + + \since BeOS R5 +*/ + + +/*! + \var B_MEDIA_PARAMETER_GROUP_TYPE + \brief Represents the BParameterGroup type from the media kit. + + \since BeOS R5 +*/ + + +/*! + \var B_MINI_ICON_TYPE + \brief Represents a 16x16 icon. \since Haiku R1 */ -// Todo: the rest of the types +/*! + \var B_LARGE_ICON_TYPE + \brief Represents a 32x32 icon. + + \since Haiku R1 +*/ /*! @@ -195,7 +367,7 @@ \var B_URL_HTTP \brief application/x-vnd.Be.URL.http - \since Haiku R1 + \since BeOS R5 */ @@ -203,7 +375,7 @@ \var B_URL_HTTPS \brief application/x-vnd.Be.URL.https - \since Haiku R1 + \since BeOS R5 */ @@ -211,7 +383,7 @@ \var B_URL_FTP \brief application/x-vnd.Be.URL.ftp - \since Haiku R1 + \since BeOS R5 */ @@ -219,7 +391,7 @@ \var B_URL_GOPHER \brief application/x-vnd.Be.URL.gopher - \since Haiku R1 + \since BeOS R5 */ @@ -227,7 +399,7 @@ \var B_URL_MAILTO \brief application/x-vnd.Be.URL.mailto - \since Haiku R1 + \since BeOS R5 */ @@ -235,7 +407,7 @@ \var B_URL_NEWS \brief application/x-vnd.Be.URL.news - \since Haiku R1 + \since BeOS R5 */ @@ -243,7 +415,7 @@ \var B_URL_NNTP \brief application/x-vnd.Be.URL.nntp - \since Haiku R1 + \since BeOS R5 */ @@ -251,7 +423,7 @@ \var B_URL_TELNET \brief application/x-vnd.Be.URL.telnet - \since Haiku R1 + \since BeOS R5 */ @@ -259,7 +431,7 @@ \var B_URL_RLOGIN \brief application/x-vnd.Be.URL.rlogin - \since Haiku R1 + \since BeOS R5 */ @@ -267,7 +439,7 @@ \var B_URL_TN3270 \brief application/x-vnd.Be.URL.tn3270 - \since Haiku R1 + \since BeOS R5 */ @@ -275,7 +447,7 @@ \var B_URL_WAIS \brief application/x-vnd.Be.URL.wais - \since Haiku R1 + \since BeOS R5 */ @@ -283,7 +455,7 @@ \var B_URL_FILE \brief application/x-vnd.Be.URL.file - \since Haiku R1 + \since BeOS R5 */