Xqt has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/640171 )

Change subject: [doc] Improved doc string for logging.py function ......................................................................

[doc] Improved doc string for logging.py function

Extended doc strings for logging.py functions such as error, exception, stdout, log, critical and debug.

Bug: T85271 Change-Id: I265a5258d711a6e038b1974e4f1cf29fd5c0f650 --- M pywikibot/logging.py 1 file changed, 51 insertions(+), 5 deletions(-)

Approvals: jenkins-bot: Verified Xqt: Looks good to me, approved

diff --git a/pywikibot/logging.py b/pywikibot/logging.py index ed4e842..457e276 100644 --- a/pywikibot/logging.py +++ b/pywikibot/logging.py @@ -137,7 +137,15 @@

def stdout(text, decoder=None, newline=True, **kwargs): - """Output script results to the user via the userinterface.""" + """Output script results to the user via the userinterface. + + @param text: the message printed via stdout logger to the user. + @param decoder: If None, text should be a unicode string else it should + be encoded in the given encoding. + @param newline: If True, a line feed will be added after printing the text. + @param kwargs: The keyword arguments can be found in the python doc: + https://docs.python.org/3/howto/logging-cookbook.html. + """ logoutput(text, decoder, newline, STDOUT, **kwargs)

@@ -146,7 +154,7 @@ """Output a warning message to the user via the userinterface.

@param text: the message the user wants to display. - @param decoder: If None, text should be a unicode string. Otherwise it + @param decoder: If None, text should be a unicode string else it should be encoded in the given encoding. @param newline: If True, a line feed will be added after printing the text. @param kwargs: The keyword arguments can be found in the python doc: @@ -156,23 +164,53 @@

def error(text, decoder=None, newline=True, **kwargs): - """Output an error message to the user via the userinterface.""" + """Output an error message to the user via the userinterface. + + @param text: the message containing the error which occured. + @param decoder: If None, text should be a unicode string else it should + be encoded in the given encoding. + @param newline: If True, a line feed will be added after printing the text. + @param kwargs: The keyword arguments can be found in the python doc: + https://docs.python.org/3/howto/logging-cookbook.html. + """ logoutput(text, decoder, newline, ERROR, **kwargs)

def log(text, decoder=None, newline=True, **kwargs): - """Output a record to the log file.""" + """Output a record to the log file. + + @param text: the message which is to be logged to the log file. + @param decoder: If None, text should be a unicode string else it should + be encoded in the given encoding. + @param newline: If True, a line feed will be added after printing the text. + @param kwargs: The keyword arguments can be found in the python doc: + https://docs.python.org/3/howto/logging-cookbook.html. + """ logoutput(text, decoder, newline, VERBOSE, **kwargs)

def critical(text, decoder=None, newline=True, **kwargs): - """Output a critical record to the user via the userinterface.""" + """Output a critical record to the user via the userinterface. + + @param text: the critical message which is to be displayed to the user. + @param decoder: If None, text should be a unicode string else it should + be encoded in the given encoding. + @param newline: If True, a line feed will be added after printing the text. + @param kwargs: The keyword arguments can be found in the python doc: + https://docs.python.org/3/howto/logging-cookbook.html. + """ logoutput(text, decoder, newline, CRITICAL, **kwargs)

def debug(text, layer, decoder=None, newline=True, **kwargs): """Output a debug record to the log file.

+ @param text: the message of the debug record to be logged to the log file. + @param decoder: If None, text should be a unicode string else it should + be encoded in the given encoding. + @param newline: If True, a line feed will be added after printing the text. + @param kwargs: The keyword arguments can be found in the python doc: + https://docs.python.org/3/howto/logging-cookbook.html. @param layer: The name of the logger that text will be sent to. """ logoutput(text, decoder, newline, DEBUG, layer, **kwargs) @@ -195,6 +233,14 @@ pywikibot.exception(e) ...

+ This function should only be called from an Exception handler. + + @param msg: If not None,contains the description of the exception occured. + @param decoder: If None, text should be a unicode string else it should + be encoded in the given encoding. + @param newline: If True, a line feed will be added after printing the text. + @param kwargs: The keyword arguments can be found in the python doc: + https://docs.python.org/3/howto/logging-cookbook.html. @param tb: Set to True in order to output traceback also. """ if isinstance(msg, BaseException):