Fix various Doxygen warnings in Haiku book.

- Return tags for methods that don't return anything
- ingroup without matching defgroup
- confusion between ref, a, and link tags (they are not the same)
- missed API changes (BObjectList templated owning, new url
  encode/decode API)
- duplicate defgroup definitions

Change-Id: I94a31b04a10a62e71659522c5ed77098728c0843
Reviewed-on: https://review.haiku-os.org/c/haiku/+/9689
Tested-by: Commit checker robot <[email protected]>
Reviewed-by: waddlesplash <[email protected]>

docs/user/Doxyfile

@@ -938,6 +938,7 @@ INPUT                  = . \
                          ../../headers/os/game \
                          ../../headers/os/interface \
                          ../../headers/private/interface/ToolTip.h \
+                         ../../headers/os/kernel/fs_query.h \
                          ../../headers/private/kernel/condition_variable.h \
                          ../../headers/os/locale \
                          ../../headers/os/mail \
@@ -949,6 +950,7 @@ INPUT                  = . \
                          ../../headers/os/storage \
                          ../../headers/os/support \
                          ../../headers/os/translation \
+                         ../../headers/posix/dlfcn.h \
                          ../../headers/posix/syslog.h \
                          ../../headers/posix/unistd.h \
                          ../../src/kits/game/GameProducer.h

docs/user/book.dox

@@ -117,6 +117,9 @@
 		- BKeyStore
 
 
+	\defgroup device Device Kit
+	\brief The Device Kit provides access to devices such as joysticks and serial ports.
+
 	\defgroup game Game Kit
 	\brief The Game Kit provides classes for producing game sounds and
 		working with full screen apps.
@@ -125,6 +128,10 @@
 	\defgroup interface Interface Kit
 	\brief API for displaying a graphical user interface.
 
+	\defgroup kernel Kernel Kit
+	\brief The Kernel Kit provides low-level APIs mainly of use for writing device drivers and
+		kernel modules.
+
 	\defgroup locale Locale Kit
 	\brief Collection of classes for localizing applications.
 
@@ -565,9 +572,6 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
 
 	\defgroup libbe Main C++ library (libbe.so)
 
-
-	\defgroup libroot C and POSIX standard functions and extensions (libroot.so)
-	\brief Implements the C and POSIX standard libraries.
 */
 
 ///// Subgroups /////

docs/user/drivers/KernelExport.dox

@@ -192,12 +192,14 @@
 /*!
 	\fn status_t add_timer(timer *t, timer_hook hook, bigtime_t period, int32 flags)
 	\ingroup timers
-	\brief Schedule a timer to call the \ref hook function periodically or at a specified time.
+	\brief Schedule a timer to call the \a hook function periodically or at a specified time.
 
-	\param flags If B_ONE_SHOT_ABSOLUTE_TIMER, use the period as a date when the hook should be
+	\param[out] t Timer handler, for use in \ref cancel_timer.
-		called. Otherwise, use it as a period to call the hook repeatedly.
+	\param flags
-	\param flags If B_TIMER_USE_TIMER_STRUCT_TIMES, use the period defined by \ref t instead of
+		\li If B_ONE_SHOT_ABSOLUTE_TIMER, use the \a period as a date when the hook should be
-		\ref period.
+			called. Otherwise, use it as a period to call the hook repeatedly.
+		\li If B_TIMER_USE_TIMER_STRUCT_TIMES, use the period defined by \a t instead of
+			\a period.
 */
 
 /*!

docs/user/game/GameSound.dox

@@ -252,3 +252,4 @@
 	\since BeOS R4.5
 */
 
+//! @}

docs/user/interface/AffineTransform.dox

@@ -90,9 +90,6 @@
 	\fn BAffineTransform::BAffineTransform()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -108,9 +105,6 @@
 	\param tx Undocumented
 	\param ty Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -121,9 +115,6 @@
 
 	\param copyFrom Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -132,9 +123,6 @@
 	\fn virtual virtual BAffineTransform::~BAffineTransform()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/interface/Alignment.dox

@@ -50,9 +50,6 @@
 	\fn BAlignment::BAlignment()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -63,9 +60,6 @@
 
 	\param other Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -77,9 +71,6 @@
 	\param horizontal Undocumented
 	\param vertical Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/interface/ChannelControl.dox

@@ -44,9 +44,6 @@
 	\param resizingMode Undocumented
 	\param flags Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -61,9 +58,6 @@
 	\param channelCount Undocumented
 	\param flags Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -74,9 +68,6 @@
 
 	\param archive Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -85,9 +76,6 @@
 	\fn virtual virtual BChannelControl::~BChannelControl()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/interface/ChannelSlider.dox

@@ -42,9 +42,6 @@
 	\param resizeMode Undocumented
 	\param flags Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -62,9 +59,6 @@
 	\param resizeMode Undocumented
 	\param flags Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -80,9 +74,6 @@
 	\param channels Undocumented
 	\param flags Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -93,9 +84,6 @@
 
 	\param archive Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -104,9 +92,6 @@
 	\fn virtual virtual BChannelSlider::~BChannelSlider()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/interface/Deskbar.dox

@@ -34,9 +34,6 @@
 	\fn BDeskbar::BDeskbar()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -45,9 +42,6 @@
 	\fn BDeskbar::~BDeskbar()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/interface/Input.dox

@@ -39,9 +39,6 @@
 	\fn BInputDevice::~BInputDevice()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -158,7 +155,7 @@
 
 /*!
 	\enum input_method_op
-	\ingroup <kit name>
+	\ingroup interface
 	\brief Undocumented enum.
 
 	\since Haiku R1

docs/user/interface/OptionControl.dox

@@ -44,9 +44,6 @@
 	\param resizeMask Undocumented
 	\param flags Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -60,9 +57,6 @@
 	\param message Undocumented
 	\param flags Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -71,9 +65,6 @@
 	\fn virtual virtual BOptionControl::~BOptionControl()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/interface/SeparatorView.dox

@@ -37,9 +37,6 @@
 	\param orientation Undocumented
 	\param border Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -54,9 +51,6 @@
 	\param border Undocumented
 	\param alignment Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -71,9 +65,6 @@
 	\param border Undocumented
 	\param alignment Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -87,9 +78,6 @@
 	\param border Undocumented
 	\param alignment Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -103,9 +91,6 @@
 	\param border Undocumented
 	\param alignment Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -116,9 +101,6 @@
 
 	\param archive Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -127,9 +109,6 @@
 	\fn virtual virtual BSeparatorView::~BSeparatorView()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/interface/StatusBar.dox

@@ -39,9 +39,6 @@
 	\param label Undocumented
 	\param trailingLabel Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -54,9 +51,6 @@
 	\param label Undocumented
 	\param trailingLabel Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -67,9 +61,6 @@
 
 	\param archive Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -78,9 +69,6 @@
 	\fn virtual virtual BStatusBar::~BStatusBar()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/interface/Window.dox

@@ -1298,24 +1298,6 @@
 //! @{
 
 
-/*!
-	\fn void BWindow::AddShortcut(uint32 key, uint32 modifiers, BMenuItem* item)
-	\brief Creates a keyboard shortcut that activates a menu \a item.
-
-	\param key The character that activates the shortcut, case-insensitive.
-	\param modifiers A bit mask of modifiers in addition to \c B_COMMAND_KEY,
-	       options include:
-	       - \c B_SHIFT_KEY
-	       - \c B_OPTION_KEY
-	       - \c B_CONTROL_KEY
-	       - \c B_MENU_KEY
-	       To remove \c B_COMMAND_KEY specify \c B_NO_COMMAND_KEY.
-	\param item The menu \a item to activate.
-
-	\since Haiku R1
-*/
-
-
 /*!
 	\fn void BWindow::AddShortcut(uint32 key, uint32 modifiers, BMessage* message)
 	\brief Creates a keyboard shortcut that sends a \a message to the window.

docs/user/locale/UnicodeChar.dox

@@ -278,7 +278,7 @@
 	\fn void BUnicodeChar::ToUTF8(uint32 c, char** out)
 	\brief Transform a character to UTF-8 encoding.
 
-	\returns The UTF-8 encoding of the specified unicode character.
+	\param[out] out Set to the UTF-8 encoding of the specified unicode character.
 
 	\since Haiku R1
 */

docs/user/posix/_libroot.dox

@@ -8,6 +8,7 @@
 
 /*!
 \defgroup libroot C, POSIX, GNU and BSD functions
+\brief Implements the C and POSIX standard libraries.
 
 Haiku implements a standard library containing the standard functions from C
 (https://www.iso.org/standard/29237.html) and POSIX

docs/user/shared/_libshared.dox

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Adrien Destugues, [email protected]
+ */
+
+/*!
+\defgroup libshared Experimental functions and classes
+\brief Static library for experimental and work-in progress code.
+
+The main Haiku libraries (libroot, libbe and others) are provided as shared libraries.
+This means in most cases, the ABI and API of functions and classes defined therein cannot be
+changed without breaking existing applications that use them.
+
+This makes it difficult to expose work-in-progress code in these libraries, as any change of
+interface would require all applications using the old interface to be recompiled.
+
+libshared provides a solution for that. It is provided as a static library, which means
+applications using it will embed a fixed version of the libsared code that they were compiled
+against. This way, updates to the library do not affect already compiled binaries, and developers
+can update to a new version of libshared (and make any needed changes) when they recompile their
+code.
+
+All functions and classes in libshared are additionally put in the BPrivate namespace. When an
+API is deemed mature, its final version can be moved to a shared library, and at the same time,
+moved out of the namespace. This makes sure applications that are still using a version from
+libshared do not get interferenced by the newly introduced public version.
+*/

docs/user/storage/_libtracker.dox

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2025 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Adrien Destugues, [email protected]
+ */
+
+/*!
+\defgroup libtracker Tracker Kit
+\brief Tracker components for use in other applications.
+
+This kit provides user interface and filesystem classes that are part of the Tracker file manager,
+but are useful to other applications as well.
+*/

docs/user/storage/storageintro.dox

@@ -32,7 +32,7 @@ filesystem hierarchy is available for non packaged software. This can be used to
 locally that is not available yet in HPKG form (for example, as a destination for "make install").
 
 For a complete list of directories and how to access them in a way that is safe to future
-filesystem reorganizations, see \link find_directory, \link find_path, and \link BPathFinder.
+filesystem reorganizations, see \ref find_directory, \ref find_path, and \ref BPathFinder.
 
 */
 

docs/user/support/BufferedDataIO.dox

@@ -42,9 +42,6 @@
 	\param ownsStream Undocumented
 	\param partialReads Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -53,9 +50,6 @@
 	\fn virtual virtual BBufferedDataIO::~BBufferedDataIO()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/support/ObjectList.dox

@@ -30,12 +30,11 @@
 
 
 /*!
-	\fn template<class T> BObjectList<T>::BObjectList(int32 itemsPerBlock,
+	\fn template<class T, bool owning> BObjectList<T>::BObjectList(int32 itemsPerBlock)
-		bool owning)
 	\brief Creates a new BObjectList.
 
 	\param itemsPerBlock The number of items per block to allocate.
-	\param owning Whether or not the BObjectList deletes its items when
+	\tparam owning Whether or not the BObjectList deletes its items when
 	       it is emptied or deleted.
 
 	\since Haiku R1
@@ -43,8 +42,8 @@
 
 
 /*!
-	\fn template<class T> BObjectList<T>::BObjectList(
+	\fn template<class T, bool owning> BObjectList<T>::BObjectList(
-		const BObjectList<T>& list)
+		const BObjectList& list)
 	\brief Creates a new BObjectList as a copy of another \a list.
 
 	\param list The \a list to copy from.
@@ -54,7 +53,7 @@
 
 
 /*!
-	\fn template<class T> BObjectList<T>::~BObjectList()
+	\fn template<class T, bool owning> BObjectList<T>::~BObjectList()
 	\brief Deletes the list.
 
 	If the list owns its items they are deleted too.
@@ -72,7 +71,7 @@
 
 
 /*!
-	\fn template<class T> BObjectList<T>& BObjectList<T>::operator=(
+	\fn template<class T, bool owning> BObjectList<T>& BObjectList<T>::operator=(
 		const BObjectList<T>& list)
 	\brief Creates a new BObjectList as a copy of another \a list by
 	       overloading the = operator.
@@ -126,7 +125,7 @@
 
 
 /*!
-	\fn template<class T> bool BObjectList<T>::AddList(BObjectList<T>* list)
+	\fn template<class T, bool owning> bool BObjectList<T>::AddList(BObjectList* list)
 	\brief Append a \a list of items to this list.
 
 	The original list is not altered.
@@ -142,7 +141,7 @@
 
 
 /*!
-	\fn template<class T> bool BObjectList<T>::AddList(BObjectList<T>* list,
+	\fn template<class T, bool owning> bool BObjectList<T>::AddList(BObjectList* list,
 		int32 index)
 	\brief Add a \a list of items to this list at the specified \a index.
 

docs/user/support/StringList.dox

@@ -36,9 +36,6 @@
 
 	\param count Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -49,9 +46,6 @@
 
 	\param other Undocumented
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 
@@ -60,9 +54,6 @@
 	\fn virtual virtual BStringList::~BStringList()
 	\brief Undocumented public method
 
-	\return Undocumented
-	\retval <value> Undocumented
-
 	\since Haiku R1
 */
 

docs/user/support/Url.dox

@@ -574,35 +574,6 @@
 */
 
 
-/*!
-	\fn static static BString BUrl::UrlEncode(const BString &url, bool strict=false, bool directory=false)
-	\brief Undocumented public method
-
-	\param url Undocumented
-	\param strict Undocumented
-	\param directory Undocumented
-
-	\return Undocumented
-	\retval <value> Undocumented
-
-	\since Haiku R1
-*/
-
-
-/*!
-	\fn static static BString BUrl::UrlDecode(const BString &url, bool strict=false)
-	\brief Undocumented public method
-
-	\param url Undocumented
-	\param strict Undocumented
-
-	\return Undocumented
-	\retval <value> Undocumented
-
-	\since Haiku R1
-*/
-
-
 /*!
 	\fn static static BArchivable* BUrl::Instantiate(BMessage *archive)
 	\brief Undocumented public method