Header annotations project
Roughly prioritized TODO list of 2023 Codeathon projects to add/fix/verify Doxygen-annotated comments in public headers.
You can find the published Doxygen output from the EPICS 7.0.7 release here.
Many of the headers in Base already have annotations, which can be good examples to follow if you're not sure how to do something. If you find a file marked as "Done" below which still needs work, please un-check it here an add a note that it's incomplete. There are also files which don't appear in this list which might be worth working on, if unsure about them please ask.
Some header files come in different versions that are specific to a particular OS (in subdirectories under modules/libcom/src/osi/os), or to a particular compiler (in subdirectories under modules/libcom/src/osi/compiler). Doxygen only extracts annotations from the files that were installed in the top-level include directory tree for the host OS and compiler used. For now we've been concentrating on the Linux and GCC versions, but if you're using a different compiler or OS you can annotate those one as well (the Linux/GCC version might already have been done, so copy the annotation comments from there if it has).
Please edit this Wiki page to "claim" a file by adding your @name to it in the appropriate list below, then once you've finished you can add a link to your PR as well. The check-box will be marked as completed after your PR has been merged.
These steps should be sufficient to get started, assuming you have all the necessary programs installed:
$ git clone git@github.com:epics-base/epics-base.git base-7.0
...
$ cd base-7.0
$ make inc
$ cd documentation
$ make
The make inc command performs the minimal necessary build steps to install the header files and generate and install the HTML files that Doxygen depends on or will link to. Running make in the documentation directory runs Doxygen against the header files in the include directories and generates output files in an html directory inside your `documentation/O.$(EPICS_HOST_ARCH)' build directory.
Some of these APIs were documented in the old Application Developers Guide, looking for the header filename or routine names on the Index page is a quick way to find out.
Add your annotations by editing the header files in their original source directory and not in the include install directories — if you find yourself trying to edit a read-only file you're editing the installed copy, not the original. To look at the results, run make inc in the nearest parent of your source directory that contains an O.Common subdirectory, then go up to the documentation directory again and run make there to re-run Doxygen.
If you don't have experience using GitHub to create a Pull Request, ask other participants if they can help you.
The files listed below are for common public APIs that do not yet have Doxygen annotations.
- asLib.h - Martin Stegler
- epicsConvert.h - Martin Stegler
- epicsEndian.h - Martin Stegler
- epicsFindSymbol.h - Martin Stegler
- epicsInterrupt.h - Martin Stegler
- epicsTimer.h - Martin Stegler
- errMdef.h - Martin Stegler
- errSymTbl.h - Martin Stegler
- generalTimeSup.h - Martin Stegler
- gpHash.h- Martin Stegler
- iocLog.h - Martin Stegler
- taskwd.h- Martin Stegler
These APIs are documented in the Channel Access Reference Manual (html/CAref.html in your Base tree after the make inc step above).
- addrList.h - Martin Stegler
- cadef.h - Martin Stegler
- caerr.h - Martin Stegler
- caeventmask.h - Martin Stegler
- db_access.h - Martin Stegler
- callback.h - Martin Stegler
- dbAccess.h
- dbAccessDefs.h
- dbAddr.h
- dbBase.h
- dbEvent.h
- dbExtractArray.h
- dbLoadTemplate.h
- dbLock.h
- dbNotify.h
- dbScan.h
- dbServer.h
- dbStaticLib.h
- db_access_routines.h
- db_convert.h
- db_field_log.h
- guigroup.h
- iocInit.h
- link.h
- recGbl.h
- recSup.h
- special.h
- cvtTable.h
- dbBkpt.h
- dbCa.h
- dbCaTest.h
- dbConstLink.h
- dbConvertFast.h
- dbConvert.h
- dbConvertJSON.h
- dbDbLink.h
- dbFldTypes.h
- dbJLink.h
- registryCommon.h
- registryDeviceSupport.h
- registryDriverSupport.h
- registryFunction.h
- registry.h
- registryJLinks.h
- rsrv.h
The headers listed below are for internal use, or are less common APIs that may be deprecated.
- epicsMemFs.h
- epicsNtp.h
- epicsRtemsInitHooks.h
- epicsSingleton.h
- epicsThreadPool.h
- fdManager.h
- fdmgr.h
- libComRegister.h
- locationException.h
- osiClockTime.h
- osiPoolStatus.h
- osiWireFormat.h
- resourceLib.h
- tsDLList.h
- tsFreeList.h
- tsMinMax.h
- tsSLList.h
- caDiagnostics.h
- caProto.h
- caVersion.h
- cacIO.h
- net_convert.h
- asCa.h
- asDbLib.h
- asIocRegister.h
- dbIocRegister.h
- dbStaticIocRegister.h
- dbtoolsIocRegister.h
- iocshRegisterCommon.h
- miscIocRegister.h
- registryIocRegister.h
- registryRecordType.h