From 6c92dd471498a8aa318e9ceb078cbc8936480e14 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pekka=20Kl=C3=A4rck?= <peke@iki.fi>
Date: Fri, 28 Oct 2022 13:57:00 +0300
Subject: [PATCH] Enhance docs of Libdoc's public API. Fixes #4520.

---
 src/robot/libdoc.py             | 10 ++++++----
 src/robot/libdocpkg/__init__.py |  5 +----
 src/robot/libdocpkg/builder.py  | 28 ++++++++++++++++++++++++++--
 src/robot/libdocpkg/model.py    |  4 ++++
 utest/libdoc/test_libdoc_api.py |  4 ++++
 5 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/src/robot/libdoc.py b/src/robot/libdoc.py
index 4df5b93fec4..74045608e69 100755
--- a/src/robot/libdoc.py
+++ b/src/robot/libdoc.py
@@ -23,10 +23,12 @@
     python -m robot.libdoc
     python path/to/robot/libdoc.py
 
-Instead of ``python`` it is possible to use also other Python interpreters.
+This module also exposes the following public API:
 
-This module also provides :func:`libdoc` and :func:`libdoc_cli` functions
-that can be used programmatically. Other code is for internal usage.
+- :func:`libdoc_cli` function for simple command line tools.
+- :func:`libdoc` function as a high level programmatic API.
+- :func:`~robot.libdocpkg.builder.LibraryDocumentation` as the API to generate
+  :class:`~robot.libdocpkg.model.LibraryDoc` instances.
 
 Libdoc itself is implemented in the :mod:`~robot.libdocpkg` package.
 """
@@ -255,7 +257,7 @@ def libdoc(library_or_resource, outfile, name='', version='', format=None,
 
     :param library_or_resource: Name or path of the library or resource
         file to be documented.
-    :param outfile: Path path to the file where to write outputs.
+    :param outfile: Path to the file where to write outputs.
     :param name: Custom name to give to the documented library or resource.
     :param version: Version to give to the documented library or resource.
     :param format: Specifies whether to generate HTML, XML or JSON output.
diff --git a/src/robot/libdocpkg/__init__.py b/src/robot/libdocpkg/__init__.py
index 7ca6db75272..fac429867fa 100644
--- a/src/robot/libdocpkg/__init__.py
+++ b/src/robot/libdocpkg/__init__.py
@@ -15,10 +15,7 @@
 
 """Implements the `Libdoc` tool.
 
-The command line entry point and programmatic interface for Libdoc
-are provided by the separate :mod:`robot.libdoc` module.
-
-This package is considered stable but it is not part of the public API.
+The public Libdoc API is exposed via the :mod:`robot.libdoc` module.
 """
 
 from .builder import LibraryDocumentation
diff --git a/src/robot/libdocpkg/builder.py b/src/robot/libdocpkg/builder.py
index 4b38fcdbb39..6bb3b2a9a1c 100644
--- a/src/robot/libdocpkg/builder.py
+++ b/src/robot/libdocpkg/builder.py
@@ -27,8 +27,32 @@
 XML_EXTENSIONS = ('xml', 'libspec')
 
 
-def LibraryDocumentation(library_or_resource, name=None, version=None,
-                         doc_format=None):
+def LibraryDocumentation(library_or_resource, name=None, version=None, doc_format=None):
+    """Generate keyword documentation for the given library, resource or suite file.
+
+    :param library_or_resource:
+        Name or path of the library, or path of a resource or a suite file.
+    :param name:
+        Set name with the given value.
+    :param version:
+        Set version to the given value.
+    :param doc_format:
+        Set documentation format to the given value.
+    :return:
+        :class:`~.model.LibraryDoc` instance.
+
+    This factory method is the recommended API to generate keyword documentation
+    programmatically. It should be imported via the :mod:`robot.libdoc` module.
+
+    Example::
+
+        from robot.libdoc import LibraryDocumentation
+
+        lib = LibraryDocumentation('OperatingSystem')
+        print(lib.name, lib.version)
+        for kw in lib.keywords:
+            print(kw.name)
+    """
     builder = DocumentationBuilder(library_or_resource)
     libdoc = _build(builder, library_or_resource)
     if name:
diff --git a/src/robot/libdocpkg/model.py b/src/robot/libdocpkg/model.py
index efa17b4f6bf..2b7c4a12288 100644
--- a/src/robot/libdocpkg/model.py
+++ b/src/robot/libdocpkg/model.py
@@ -27,6 +27,7 @@
 
 
 class LibraryDoc:
+    """Documentation for a library, a resource file or a suite file."""
 
     def __init__(self, name='', doc='', version='', type='LIBRARY', scope='TEST',
                  doc_format='ROBOT', source=None, lineno=-1):
@@ -67,10 +68,12 @@ def doc_format(self, format):
 
     @setter
     def inits(self, inits):
+        """Initializer docs as :class:`~KeywordDoc` instances."""
         return self._process_keywords(inits)
 
     @setter
     def keywords(self, kws):
+        """Keyword docs as :class:`~KeywordDoc` instances."""
         return self._process_keywords(kws)
 
     @setter
@@ -146,6 +149,7 @@ def to_json(self, indent=None, include_private=True, theme=None):
 
 
 class KeywordDoc(Sortable):
+    """Documentation for a single keyword or an initializer."""
 
     def __init__(self, name='', args=None, doc='', shortdoc='', tags=(), private=False,
                  deprecated=False, source=None, lineno=-1, parent=None):
diff --git a/utest/libdoc/test_libdoc_api.py b/utest/libdoc/test_libdoc_api.py
index de2ea0957c9..d305ee26c55 100644
--- a/utest/libdoc/test_libdoc_api.py
+++ b/utest/libdoc/test_libdoc_api.py
@@ -43,6 +43,10 @@ def test_quiet(self):
         with open(output) as f:
             assert '"name": "String"' in f.read()
 
+    def test_LibraryDocumentation(self):
+        doc = libdoc.LibraryDocumentation('OperatingSystem')
+        assert_equal(doc.name, 'OperatingSystem')
+
 
 if __name__ == '__main__':
     unittest.main()