Details
-
Type:
Bug
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: log, pex_logging
-
Labels:None
-
Team:Data Release Production
Description
The logging documentation for the LSST stack is confusing. There are two packages, listed very far apart from each other, with no indication of why there are two packages nor which one should be used for our code.
I strongly suggest that each package's main.dox file be updated to address this issue. It should clearly mention the existence of other package and give a rough idea of which one is to be used.
Here is the original description of this ticket, which may clarify the initial comments:
The pex_logging main page, which has a useful overview and tutorial, seems to not match the actual implementation anymore, at least for the python interface. For instance main.dox http://lsst-web.ncsa.illinois.edu/doxygen/x_masterDoxyDoc/log.html says:
In Python, the following logging functions are available in the lsst.log module. These functions take a variable number of arguments following a format string in the style of printf(). The use of *args is recommended over the use of the % operator so that formatting of log messages that do not meet the level threshold can be avoided.
I didn't actually expect pex_logging to contain such a free function (though that's what the documentation says) but I did expect the Log function to contain that method. It doesn't. Instead it has a logdebug method (different name) that does not seem to accept the arguments described above (though naturally it does accept a single string).
Unless I'm missing something the overview needs some significant work.
I believe this is still in Jacek's domain