DUNE-DAQ / logging

DUNE DAQ logging package
0 stars 0 forks source link

User-oriented documentation #11

Open jcfreeman2 opened 3 years ago

jcfreeman2 commented 3 years ago

If you can see this Issue, it means that the existing documentation for this package has already been added to the official documentation, https://dune-daq-sw.readthedocs.io/en/latest, via its placement in your repo's docs/ directory. The next step is to make sure that the documentation in docs/ tells your package's users (as opposed to developers) everything they need to know about the package. The goal is to get this done for the dunedaq-v2.4.1 release in a couple weeks.

For details/hints please see https://dune-daq-sw.readthedocs.io/en/latest/editing_package_documentation/.

bieryAtFnal commented 3 years ago

There is probably a better place to put this comment, but I will add it here, for now.

I tried to update the docs/README.md file before I remembered that I don't have access to the logging package. My goal was the following:

The proposed changes in README.md were the following:

diff --git a/docs/README.md b/docs/README.md
index 3d77719..ac0ff69 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,20 +6,21 @@ The primary user documentation starting point for the DUNE fork of ERS is found
 One link to TRACE information can be found [here](https://cdcvs.fnal.gov/redmine/projects/trace/wiki).

 ERS provides:
-- Assertion Macros
-- Macros for declaring Custom Issues
-- 6 logging streams and corresponding methods to work with (i.e. send to) them.
-- a mechanism to configure destination(s) for each of 6 loggings streams
+* Assertion Macros
+* Macros for declaring Custom Issues
+* 6 logging streams and corresponding methods to work with (i.e. send to) them.
+* a mechanism to configure destination(s) for each of 6 loggings streams

 ERS also provides Logging Macros, but these have been removed in the DUNE DAQ fork.

 TRACE provides:
-- several macros to implement stream-style logging to different logging levels.
-- slow and fast-path logging
-- a mechanism to configure the slow-path logging, i.e to use ERS as the slow-path logging.
+* several macros to implement stream-style logging to different logging levels.
+* slow and fast-path logging (where "fast" corresponds to a memory-mapped file and "slow" corresponds to the console, a disk file, or anothe
+* a mechanism to configure the slow-path logging, i.e to use ERS as the slow-path logging.

-<details><summary>One of the ERS *destinations* for first 4 of the 6 loggings
-*streams* will be a "TRACE fast path destination."</summary>
+<details><summary>All messages that are sent to one of the ERS streams will also be sent to the TRACE fast path.</summary>
+This is achieved by specifying one of the ERS *destinations* for first 4 of the 6 loggings
+*streams* to be the "TRACE fast path destination."
 The Logging package setup function will ensure that the environment variables DUNEDAQ_ERS_{FATAL,ERROR,WARNING,INFO} (used to configure the 

 Only two of the TRACE logging macros (TLOG() and TLOG_DEBUG()) will be used and TRACE will be configured to use ERS for the slow-path loggin