diff mbox series

[2/4] lib/bb: format and improve logging docstrings

Message ID 20250418-library-functions-v1-2-3bbb836149d7@bootlin.com
State Accepted, archived
Commit 4963bfc6045ad1f49e721edd97766dab1e2d1edc
Headers show
Series Document library functions | expand

Commit Message

Antonin Godard April 18, 2025, 3:15 p.m. UTC 
Format the docstrings of the utils modules to be automatically
documented with the autodoc Sphinx extensions.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 lib/bb/__init__.py | 76 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 70 insertions(+), 6 deletions(-)

Comments

Quentin Schulz April 22, 2025, 4:49 p.m. UTC | #1 
Hi Antonin,

On 4/18/25 5:15 PM, Antonin Godard via lists.openembedded.org wrote:
> Format the docstrings of the utils modules to be automatically
> documented with the autodoc Sphinx extensions.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   lib/bb/__init__.py | 76 +++++++++++++++++++++++++++++++++++++++++++++++++-----
>   1 file changed, 70 insertions(+), 6 deletions(-)
> 
> diff --git a/lib/bb/__init__.py b/lib/bb/__init__.py
> index 566835573..c95c91a4c 100644
> --- a/lib/bb/__init__.py
> +++ b/lib/bb/__init__.py
> @@ -129,9 +129,25 @@ sys.modules['bb.fetch'] = sys.modules['bb.fetch2']
>   
>   # Messaging convenience functions
>   def plain(*args):
> +    """
> +    Prints a message at "plain" level (higher level than a ``bb.note()``).
> +
> +    Arguments:
> +
> +    -  ``args``: one or more strings to print.

Maybe specify that no space is added between strings?

Same remark for all other log functions.

> +    """
>       mainlogger.plain(''.join(args))
>   
>   def debug(lvl, *args):
> +    """
> +    Prints a debug message.
> +

You nicely have specified in plain() that it is lower than note() but 
you don't say something similar than debug, what is the closest but 
higher loglevel?

Same remark for all other log functions.

> +    Arguments:
> +
> +    -  ``lvl``: debug level. Higher value increases the debug level
> +       (determined by ``bitbake -D``).

It is an integer though.

What's the allowed values for the lvl? I see debug2 and debug3 so I 
assume 0 to 3 maybe?

Cheers,
Quentin
diff mbox series

Patch

diff --git a/lib/bb/__init__.py b/lib/bb/__init__.py
index 566835573..c95c91a4c 100644
--- a/lib/bb/__init__.py
+++ b/lib/bb/__init__.py
@@ -129,9 +129,25 @@  sys.modules['bb.fetch'] = sys.modules['bb.fetch2']
 
 # Messaging convenience functions
 def plain(*args):
+    """
+    Prints a message at "plain" level (higher level than a ``bb.note()``).
+
+    Arguments:
+
+    -  ``args``: one or more strings to print.
+    """
     mainlogger.plain(''.join(args))
 
 def debug(lvl, *args):
+    """
+    Prints a debug message.
+
+    Arguments:
+
+    -  ``lvl``: debug level. Higher value increases the debug level
+       (determined by ``bitbake -D``).
+    -  ``args``: one or more strings to print.
+    """
     if isinstance(lvl, str):
         mainlogger.warning("Passed invalid debug level '%s' to bb.debug", lvl)
         args = (lvl,) + args
@@ -139,33 +155,81 @@  def debug(lvl, *args):
     mainlogger.bbdebug(lvl, ''.join(args))
 
 def note(*args):
+    """
+    Prints a message at "note" level.
+
+    Arguments:
+
+    -  ``args``: one or more strings to print.
+    """
     mainlogger.info(''.join(args))
 
-#
-# A higher prioity note which will show on the console but isn't a warning
-#
-# Something is happening the user should be aware of but they probably did
-# something to make it happen
-#
 def verbnote(*args):
+    """
+    A higher priority note which will show on the console but isn't a warning.
+
+    Use in contexts when something is happening the user should be aware of but
+    they probably did something to make it happen.
+
+    Arguments:
+
+    -  ``args``: one or more strings to print.
+    """
     mainlogger.verbnote(''.join(args))
 
 #
 # Warnings - things the user likely needs to pay attention to and fix
 #
 def warn(*args):
+    """
+    Prints a warning message.
+
+    Arguments:
+
+    -  ``args``: one or more strings to print.
+    """
     mainlogger.warning(''.join(args))
 
 def warnonce(*args):
+    """
+    Prints a warning message like ``bb.warn()``, but only prints the message
+    once.
+
+    Arguments:
+
+    -  ``args``: one or more strings to print.
+    """
     mainlogger.warnonce(''.join(args))
 
 def error(*args, **kwargs):
+    """
+    Prints an error message.
+
+    Arguments:
+
+    -  ``args``: one or more strings to print.
+    """
     mainlogger.error(''.join(args), extra=kwargs)
 
 def erroronce(*args):
+    """
+    Prints an error message like ``bb.error()``, but only prints the message
+    once.
+
+    Arguments:
+
+    -  ``args``: one or more strings to print.
+    """
     mainlogger.erroronce(''.join(args))
 
 def fatal(*args, **kwargs):
+    """
+    Prints an error message and stops the BitBake execution.
+
+    Arguments:
+
+    -  ``args``: one or more strings to print.
+    """
     mainlogger.critical(''.join(args), extra=kwargs)
     raise BBHandledException()