Project

General

Profile

Support #6334

Document API using a tool such as Doxygen

Added by Ben Morgan over 5 years ago. Updated almost 2 years ago.

Status:
Feedback
Priority:
Normal
Assignee:
-
Target version:
-
Start date:
05/23/2014
Due date:
% Done:

0%

Estimated time:
Duration:

Description

Though the wiki page provides some hints, it would be useful to have the API of cetlib documented.

This could use a suitable markup tool such as Doxygen.


Related issues

Related to fhicl-cpp - Support #6337: Document API using a tool such as DoxygenFeedback05/23/2014

Related to messagefacility - Support #6338: Document Message Facility API using a tool such as DoxygenFeedback05/23/2014

History

#1 Updated by Christopher Green over 5 years ago

  • Tracker changed from Feature to Support
  • Status changed from New to Feedback

We would like to discuss this at the stakeholders meeting, since this does entail a significant amount of effort from the point of view of both the tool choice and configuration for automatic use, and the documentation of the APIs in the chosen format. Please note that we do have the ongoing art workbook project, where you may find some of the information you seek.

#2 Updated by Kyle Knoepfel over 4 years ago

  • Target version set to 521

#3 Updated by Ben Morgan over 3 years ago

I've attached a patch that adds the simplest way to add a target to build Doxygen pages for cetlib.

  • A doc target is created if Doxygen is found (so just make doc after configuration)
  • Information from the Cmake configuration is used to configure the input file
  • Generated pages are output to a Doxygen subdirectory of the build directory
  • At least HTML docs are generated, and can be viewed by opening PROJECT_BINARY_DIR/Doxygen/html/index.html in your browser
  • The source:README file is renamed with a .md extension and used as the main page (as doxygen can parse markdown)
  • All items are extracted, even if not documented
  • No installation of the pages is done as I wasn't clear where these should go (they're flavor independent)

This is very basic and doesn't address adding doxygen as a build requires in the source:ups/product_deps file (NB, find_package will be sufficient provided the doxygen exe is in the PATH), nor the actual documentation(!). However, it should provide an idea at least of how to get started on generating the docs...

#4 Updated by Kyle Knoepfel over 3 years ago

Thank you for your submission. We will review the patch--documentation of cetlib and other packages is a matter that requires effort and, unfortunately, project priorities have always been for new development rather than documentation.

#5 Updated by Kyle Knoepfel almost 2 years ago

  • Target version deleted (521)


Also available in: Atom PDF