From b966e837857c9c38db1a87e8dda76d9464f32168 Mon Sep 17 00:00:00 2001
From: Adrien Destugues <pulkomandy@pulkomandy.tk>
Date: Tue, 29 Dec 2020 13:59:27 +0100
Subject: [PATCH] Add some documentation for libroot

Mainly for features.h and feature defines, which seems to be an ongoing
source of confusion and not well understood.
---
 docs/user/book.dox           |  2 ++
 docs/user/posix/_libroot.dox | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 docs/user/posix/_libroot.dox

diff --git a/docs/user/book.dox b/docs/user/book.dox
index 7107a559c3..caf9ea073a 100644
--- a/docs/user/book.dox
+++ b/docs/user/book.dox
@@ -61,6 +61,7 @@
 
 	\section book_special_topics Special Topics
 
+	- \ref libroot
 	- \ref drivers
 	- \ref keyboard
 	- \ref json
@@ -583,6 +584,7 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
 
 
 	\defgroup libroot (libroot.so)
+	\brief Implements the C and POSIX standard libraries.
 */
 
 ///// Subgroups /////
diff --git a/docs/user/posix/_libroot.dox b/docs/user/posix/_libroot.dox
new file mode 100644
index 0000000000..d3bb8a03d3
--- /dev/null
+++ b/docs/user/posix/_libroot.dox
@@ -0,0 +1,33 @@
+/*
+ * Copyright 2019 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Adrien Destugues, pulkomandy@pulkomandy.tk
+ */
+
+/*!
+\page libroot C, POSIX, GNU and BSD functions
+
+Haiku implements a standard library containing the standard functions from C
+(https://www.iso.org/standard/29237.html) and POSIX
+(https://pubs.opengroup.org/onlinepubs/9699919799/). These functions are
+available in libroot, which is linked in by default.
+
+For convenience and POSIX compatibility, empty "m" and "pthread" libraries are
+also provided, but the math and thread functions are also defined in libroot.
+
+The C library also contains a number of GNU and BSD extensions to the C and
+POSIX standards. The BSD extensions are enabled by default unless a specific
+version of the C standard is requested from the compiler command line (for
+example by using the --std=c99 switch). In case you want to set the compiler
+to strict C99 but still use these extensions, you need to define _DEFAULT_SOURCE
+(with a #define preprocessor directive, or from the command line).
+
+The GNU extensions are not enabled by default, but can be enabled by defining
+_GNU_SOURCE.
+
+The GNU and BSD extensions are in a separate library, so the -lbsd linker flag
+may be needed to use them.
+
+*/