doc FEATURE high level documentation including transition manual
diff --git a/src/printer_schema.h b/src/printer_schema.h
index 1f69ff0..9ca5e7a 100644
--- a/src/printer_schema.h
+++ b/src/printer_schema.h
@@ -30,6 +30,57 @@
struct lysc_node;
struct lysp_submodule;
+
+/**
+ * @page howtoSchemaPrinters Module Printers
+ *
+ * Schema printers allows to serialize internal representations of a schema module in a specific format. libyang
+ * supports the following schema formats for printing:
+ *
+ * - YANG
+ *
+ * Basic YANG schemas format described in [RFC 6020](http://tools.ietf.org/html/rfc6020) and
+ * [RFC 7951](http://tools.ietf.org/html/rfc7951) (so both YANG 1.0 and YANG 1.1 versions are supported).
+ *
+ * - YANG compiled
+ *
+ * Syntactically, this format is based on standard YANG format. In contrast to standard YANG format, YANG compiled format
+ * represents the module how it is used by libyang - with all uses expanded, augments and deviations applied, etc.
+ * (more details about the compiled modules can be found on @ref howtoContext page).
+ *
+ * - YIN
+ *
+ * Alternative XML-based format to YANG - YANG Independent Notation. The details can be found in
+ * [RFC 6020](http://tools.ietf.org/html/rfc6020#section-11) and
+ * [RFC 7951](http://tools.ietf.org/html/rfc7951#section-13).
+ *
+ * - Tree Diagram
+ *
+ * Simple tree diagram providing overview of the module. The details can be found in
+ * [RFC 8340](https://tools.ietf.org/html/rfc8340).
+ *
+ * For simpler transition from libyang 1.x (and for some simple use cases), there are functions (::lys_print_clb(),
+ * ::lys_print_fd(), ::lys_print_file() and ::lys_print_mem()) to print the complete module into the specified output. But note,
+ * that these functions are limited to print only the complete module.
+ *
+ * The full functionality of the schema printers is available via functions using [output handler](@ref howtoPrinters). Besides
+ * the ::lys_print_module() function to print the complete module, there are functions to print a submodule
+ * (::lys_print_submodule()) or a subtree (::lys_print_node()). Note that these functions might not support all the output
+ * formats mentioned above.
+ *
+ * Functions List
+ * --------------
+ * - ::lys_print_module()
+ * - ::lys_print_submodule()
+ * - ::lys_print_node()
+ *
+ * - ::lys_print_clb()
+ * - ::lys_print_fd()
+ * - ::lys_print_file()
+ * - ::lys_print_mem()
+ * - ::lys_print_path()
+ */
+
/**
* @addtogroup schematree
* @{
@@ -37,6 +88,9 @@
/**
* @defgroup schemaprinterflags Schema output options
+ *
+ * Options to change default behavior of the schema printers.
+ *
* @{
*/
#define LYS_PRINT_SHRINK LY_PRINT_SHRINK /**< Flag for output without indentation and formatting new lines. */
@@ -50,15 +104,14 @@
/** @} schemaprinterflags */
/**
- * @brief Schema output formats accepted by libyang [printer functions](@ref howtoschemasprinters).
+ * @brief Schema output formats accepted by libyang [printer functions](@ref howtoSchemaPrinters).
*/
typedef enum {
LYS_OUT_UNKNOWN = 0, /**< unknown format, used as return value in case of error */
LYS_OUT_YANG = 1, /**< YANG schema output format */
LYS_OUT_YANG_COMPILED = 2, /**< YANG schema output format of the compiled schema tree */
LYS_OUT_YIN = 3, /**< YIN schema output format */
-
- LYS_OUT_TREE /**< Tree schema output format, for more information see the [printers](@ref howtoschemasprinters) page */
+ LYS_OUT_TREE /**< Tree schema output format */
} LYS_OUTFORMAT;
/**
@@ -79,7 +132,7 @@
* @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
* @param[in] module Main module of the submodule to print.
* @param[in] submodule Parsed submodule to print.
- * @param[in] format Output format.
+ * @param[in] format Output format (LYS_OUT_YANG_COMPILED is not supported).
* @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
@@ -91,7 +144,7 @@
* @brief Print schema tree in the specified format into a memory block.
* It is up to caller to free the returned string by free().
*
- * This is just a wrapper around lys_print() for simple use cases.
+ * This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[out] strp Pointer to store the resulting dump.
@@ -105,7 +158,7 @@
/**
* @brief Print schema tree in the specified format into a file descriptor.
*
- * This is just a wrapper around lys_print() for simple use cases.
+ * This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[in] fd File descriptor where to print the data.
@@ -119,7 +172,7 @@
/**
* @brief Print schema tree in the specified format into a file stream.
*
- * This is just a wrapper around lys_print() for simple use cases.
+ * This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[in] module Schema tree to print.
@@ -133,7 +186,7 @@
/**
* @brief Print schema tree in the specified format into a file.
*
- * This is just a wrapper around lys_print() for simple use cases.
+ * This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[in] path File where to print the schema.
@@ -147,7 +200,7 @@
/**
* @brief Print schema tree in the specified format using a provided callback.
*
- * This is just a wrapper around lys_print() for simple use cases.
+ * This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[in] module Schema tree to print.
@@ -164,7 +217,7 @@
* @brief Schema node printer.
*
* @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
- * @param[in] node Schema node to print, lys_find_node() can be used to get it from a path string.
+ * @param[in] node Schema node to print.
* @param[in] format Output format.
* @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
* @param[in] options Schema output options (see @ref schemaprinterflags).