Working under a model of "Write documentation for users of appfwk, where users can be users of its applications (e.g., daq_application) or plugins or public headers", here are some thoughts on what needs to be done:
Plenty of stuff we copied over from the Wiki should be eliminated as it's either (A) relevant only for appfwk developers, or (B) obsolete.
How do we want to incorporate the extensive documentation on schema that can be found in schema/README.md?
In general, any public headers should also be documented, whether in the official documentation and/or the body of the header itself. If we feel a given public header doesn't need to be documented, that's argument for making it not-public. Details follow.
DAQModuleManager.hpp: some in-header documentation exists, but the protected functions aren't really covered
DAQSink.hpp, DAQSource.hpp: "* @file DAQSink.hpp DAQSink class interface" should be expanded on, whether in the body of the header or on the wiki. Similarly with DAQSource.
Queue.hpp, QueueRegistry.hpp, StdDeQueue.hpp, FollyQueue.hpp: the interface of Queue.hpp can probably be skipped since it's not meant to be used by anything besides DAQSink and DAQSource, right? QueueRegistry.hpp may also fall in this category, not sure. Of course, if this is the case, we should consider moving the headers out of the public include directory. A sentence or two describing the difference between StdDeQueue and FollyQueue should be provided somewhere.
NamedObject.hpp: not very heavy on in-header documentation, although it's a pretty straightforward concept. Perhaps developers should be told when and why you'd want a named object. Also, an aside: do we need the Named base class, or can we just use NamedObject?
Logger.hpp: I need to know a bit more about this
Interruptible.hpp: is there a context in which we plan to use this? Curious to learn more, so let's add a bit about it.
CommandLineInterpreter.hpp, Application.hpp: are these going to be used by other developers, or are they implementation details for daq_application? If the latter, we don't really need to worry about documenting them, but we should move them out of the public include area.
Working under a model of "Write documentation for users of appfwk, where users can be users of its applications (e.g.,
daq_application) or plugins or public headers", here are some thoughts on what needs to be done:Plenty of stuff we copied over from the Wiki should be eliminated as it's either (A) relevant only for
appfwkdevelopers, or (B) obsolete.daq_application: Eric added documentation for this today, see https://dune-daq-sw.readthedocs.io/en/latest/packages/appfwk/Daq-Application/How do we want to incorporate the extensive documentation on schema that can be found in
schema/README.md?In general, any public headers should also be documented, whether in the official documentation and/or the body of the header itself. If we feel a given public header doesn't need to be documented, that's argument for making it not-public. Details follow.
DAQModule.hpp: we have both a largely empty section covering this in https://github.com/DUNE-DAQ/appfwk/wiki/Step-by-step-instructions-for-creating-your-own-DAQModule-package-under-v2.0.0 (last edited Nov. 24) and a page called https://github.com/DUNE-DAQ/appfwk/wiki/How-to-write-your-DAQModule (last edited June 22). However, there's a decent amount of DOxygenated documentation in https://github.com/DUNE-DAQ/appfwk/blob/develop/include/appfwk/DAQModule.hppDAQModuleManager.hpp: some in-header documentation exists, but the protected functions aren't really coveredDAQSink.hpp,DAQSource.hpp: "* @file DAQSink.hpp DAQSink class interface" should be expanded on, whether in the body of the header or on the wiki. Similarly withDAQSource.Queue.hpp,QueueRegistry.hpp,StdDeQueue.hpp,FollyQueue.hpp: the interface ofQueue.hppcan probably be skipped since it's not meant to be used by anything besidesDAQSinkandDAQSource, right?QueueRegistry.hppmay also fall in this category, not sure. Of course, if this is the case, we should consider moving the headers out of the public include directory. A sentence or two describing the difference betweenStdDeQueueandFollyQueueshould be provided somewhere.NamedObject.hpp: not very heavy on in-header documentation, although it's a pretty straightforward concept. Perhaps developers should be told when and why you'd want a named object. Also, an aside: do we need theNamedbase class, or can we just useNamedObject?Logger.hpp: I need to know a bit more about thisInterruptible.hpp: is there a context in which we plan to use this? Curious to learn more, so let's add a bit about it.ThreadHelper.hpp: Eric covers this nicely both in https://github.com/DUNE-DAQ/appfwk/wiki/ThreadHelper-Usage-Notes and https://github.com/DUNE-DAQ/appfwk/blob/develop/include/appfwk/ThreadHelper.hpp. Is there any overlap between the two documentations we can/should get rid of?CommandLineInterpreter.hpp,Application.hpp: are these going to be used by other developers, or are they implementation details fordaq_application? If the latter, we don't really need to worry about documenting them, but we should move them out of the public include area.