Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-2548

logging documentation is confusing, due to having two packages

    Details

    • Type: Bug
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: log, pex_logging
    • Labels:
      None
    • Templates:
    • 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.

        Attachments

          Activity

            People

            • Assignee:
              swinbank John Swinbank
              Reporter:
              rowen Russell Owen
              Watchers:
              Jacek Becla, John Swinbank, Kian-Tat Lim, Russell Owen, Steve Pietrowicz
            • Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Summary Panel