doc FEATURE high level documentation including transition manual
diff --git a/src/libyang.h b/src/libyang.h
index 14eb110..a5570e6 100644
--- a/src/libyang.h
+++ b/src/libyang.h
@@ -44,22 +44,22 @@
*
* @section about-features Main Features
*
- * - [Parsing (and validating) schemas](@ref howtoschemasparsers) in YANG format.
- * - [Parsing (and validating) schemas](@ref howtoschemasparsers) in YIN format.
- * - [Parsing, validating and printing instance data](@ref howtodata) in XML format.
- * - [Parsing, validating and printing instance data](@ref howtodata) in JSON format
+ * - [Parsing (and validating) schemas](@ref howtoSchema) in YANG format.
+ * - [Parsing (and validating) schemas](@ref howtoSchema) in YIN format.
+ * - [Parsing, validating and printing instance data](@ref howtoData) in XML format.
+ * - [Parsing, validating and printing instance data](@ref howtoData) in JSON format
* ([RFC 7951](https://tools.ietf.org/html/rfc7951)).
- * - [Manipulation with the instance data](@ref howtodatamanipulators).
- * - Support for [default values in the instance data](@ref howtodatawd) ([RFC 6243](https://tools.ietf.org/html/rfc6243)).
- * - Support for [YANG extensions and user types](@ref howtoschemaplugins).
- * - Support for [YANG Metadata](@ref howtoschemametadata) ([RFC 7952](https://tools.ietf.org/html/rfc6243)).
+ * - [Manipulation with the instance data](@ref howtoDataManipulation).
+ * - Support for [default values in the instance data](@ref howtoDataWD) ([RFC 6243](https://tools.ietf.org/html/rfc6243)).
+ * - Support for [YANG extensions and user types](@ref howtoPlugins).
+ * - Support for [YANG Metadata](@ref howtoPluginsExtensionsMetadata) ([RFC 7952](https://tools.ietf.org/html/rfc6243)).
*
* The current implementation covers YANG 1.0 ([RFC 6020](https://tools.ietf.org/html/rfc6020)) as well as
* YANG 1.1 ([RFC 7950](https://tools.ietf.org/html/rfc7950)).
*
* @section about-license License
*
- * Copyright (c) 2015-2017 CESNET, z.s.p.o.
+ * Copyright (c) 2015-2020 CESNET, z.s.p.o.
*
* (The BSD 3-Clause License)
*
@@ -80,15 +80,65 @@
/**
* @page howto libyang API Overview
*
- * - @subpage howtocontext
- * - @subpage howtoschemas
- * - @subpage howtodata
- * - @subpage howtoxpath
- * - @subpage howtoxml
- * - @subpage howtothreads
- * - @subpage howtologger
- * - @subpage howtoplugins
- * - @subpage howtostructures
+ * @section howtoGeneral General notes
+ *
+ * libyang is primarily intended for handling data modeled by YANG modeling language, so the library is supposed to be optimized
+ * for this purpose. However, as a side effect, the library has to be able precisely process YANG modules. Thus, it is usable by
+ * YANG module authors to validate their modules and schemas in the development process.
+ *
+ * - @subpage howtoStructures
+ * - @subpage howtoErrors
+ * - @subpage howtoLogger
+ * - @subpage howtoThreads
+ * - @subpage howtoContext
+ * - @subpage howtoParsers
+ * - @subpage howtoPrinters
+ * - @subpage howtoSchema
+ * - @subpage howtoData
+ * - @subpage howtoXPath
+ * - @subpage howtoPlugins
+ */
+
+/**
+ * @page howtoStructures Data Structures
+ *
+ * @section sizedarrays Sized Arrays
+ *
+ * The structure starts with 32bit number storing size of the array - the number of the items inside. The size is part of the
+ * array to have it allocated together with the array itself only when it is needed. However, the pointers to the array always
+ * points after the 32b number, so items can be accessed directly as for standard C arrays. Because of a known size (available
+ * via ::LY_ARRAY_COUNT macro), it is not terminated by any special byte (sequence), so there is also no limitation for specific
+ * content of the stored records (e.g. that first byte must not be NULL).
+ *
+ * The sized arrays must be carefully freed (which should be done anyway only internally), since pointers to the sized arrays used
+ * in libyang structures, does not point to the beginning of the allocated space.
+ *
+ * - ::LY_ARRAY_COUNT
+ * - ::LY_ARRAY_FOR
+ *
+ * @section struct_lists Lists
+ *
+ * The lists are structures connected via a `next` and `prev` pointers. Iterating over the siblings can be simply done by
+ * ::LY_LIST_FOR macro. Examples of such structures are ::lyd_node or ::lysc_node.
+ *
+ * The `prev` pointer is always filled. In case there is just a single item in the list, the `prev` pointer points to the
+ * item itself. Otherwise, the `prev` pointer of the first item points to the last item of the list. In contrast, the
+ * `next` pointer of the last item in the list is always NULL.
+ */
+
+/**
+ * @page howtoPlugins Plugins
+ *
+ * libyang supports several types of plugins to better support generic features of YANG that need some specific code for
+ * their specific instances in YANG schemas. This is the case of YANG types, which are derived from YANG built-in types
+ * (which are implemented by libyang), but the description of the derived type can specify some additional requirements or
+ * restriction that cannot be implemented generically and some special code is needed. The second case for libyang plugins
+ * are YANG extensions. For YANG extensions, most of the specification stays in their description (e.g. allowed substatements
+ * or place of the extension instanciation) and libyang is not able to process such a text in a generic way. In both cases,
+ * libyang provides API to provide functionality implementing the specifics of each type or extension.
+ *
+ * - @subpage howtoPluginsTypes
+ * - @subpage howtoPluginsExtensions
*/
/**
@@ -100,39 +150,6 @@
* for libyang developers. The texts should explain various decisions made and internal processes utilized in libyang.
*/
-/**
- * @page howtostructures Data Structures
- *
- * @section sizedarrays Sized Arrays
- *
- * The structure starts with 32bit number storing size of the array - the number of the items inside. The size is part of the
- * array to have it allocated together with the array itself only when it is needed. However, the pointers to the array always
- * points after the 32b number, so items can be accessed directly as for standard C arrays. Because of a known size (available
- * via ::LY_ARRAY_SIZE macro), it is not terminated by any special byte (sequence), so there is also no limitation for specific
- * content of the stored records (e.g. that first byte must not be NULL).
- *
- * The sized arrays must be carefully freed (which should be done anyway only internally), since pointers to the sized arrays used
- * in libyang structures, does not point to the beginning of the allocated space.
- *
- * - ::LY_ARRAY_SIZE
- * - ::LY_ARRAY_FOR
- *
- * @section struct_lists Lists
- *
- * The lists are structures connected via a `next` pointer. Iterating over the siblings can be simply done by ::LY_LIST_FOR macro.
- */
-
-/**
- * @page howtoplugins Plugins
- *
- * libyang supports several types of plugins to better support generic features of YANG that need some specific code for
- * their specific instances in YANG schemas. This is the case of YANG types, which are derived from YANG built-in types
- * (which are implemented by libyang), but the description of the derived type can specify some additional requirements or
- * restriction that cannot be implemented generically and some special code is needed. The second case for libyang plugins
- * are YANG extensions. For YANG extensions, most of the specification stays in their description (e.g. allowed substatements
- * or place of the extension instanciation) and libyang is not able to process such a text in a generic way. In both cases,
- * libyang provides API to provide functionality implementing the specifics of each type or extension.
- */
#ifdef __cplusplus
}
#endif