[Doc] Documentation for FDB.h #49
Conversation
|
|
tbkr
requested review from
simondsmart,
Ozaq,
danovaro,
ChrisspyB,
mcakircali and
nicolau-manubens
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## develop #49 +/- ##
========================================
Coverage 64.10% 64.10%
========================================
Files 238 238
Lines 13656 13656
Branches 1313 1313
========================================
Hits 8754 8754
Misses 4902 4902 ☔ View full report in Codecov by Sentry. |
tbkr
force-pushed
the
feature/c++-api-documentation
branch
from
44a3f30
to
497a12e
Compare
tbkr
force-pushed
the
feature/c++-api-documentation
branch
2 times, most recently
from
f2aea4b
to
5c31fff
Compare
Added some documentation for the C++-API of the FDB class. There are still some open questions linked to some of the functions. This is a first draft.
tbkr
force-pushed
the
feature/c++-api-documentation
branch
from
5c31fff
to
3e69ae6
Compare
|
For readability, I'd definitely like a dash (or colon, or some kind of separator) after a \param's keyword. e.g.: Before: Edit: I notice you did have that, and removed it. I personally strongly prefer the presence of a separator |
Your suggestion means e.g., using vscode, there is already I would strongly suggest against using |
| @@ -71,72 +71,253 @@ class FDB { | |||
|
|
|||
| // -------------- Primary API functions ---------------------------- | |||
|
|
|||
| /** Archive binary data to a FDB. | |||
| * | |||
| * \param handle eckit::message::Message to data to archive | |||
There was a problem hiding this comment.
The types can be omitted from the description. IMO this is just hard to keep in sync with the actual implementation
| eckit::DataHandle* read(const eckit::URI& uri); | ||
|
|
||
| /** Read binary data from an list of URI | ||
| * | ||
| * \param vector of uris eckit uris to the data source |
There was a problem hiding this comment.
this should be \params <name or parameter> i.e. \params uris
| DumpIterator dump(const FDBToolRequest& request, bool simple=false); | ||
|
|
||
| /// TODO: Is this function superfluous given the control() function? | ||
| // \todo Is this function superfluous given the control() function? |
There was a problem hiding this comment.
I think this was supposed to be a code comment TODO and not a doc comment TODO
There was a problem hiding this comment.
I don't know if anyone has a preference but this are the supported styles: https://www.doxygen.nl/manual/docblocks.html
- Java doc
/** Just a brief */
/**
* A brief.
* With a detail section
*/
--OR--
/**
A brief.
With a detail section
*/
- QT style doc
/*! Just a brief */
/*!
* A brief.
* With a detail section
*/
--OR--
/*!
A brief.
With a detail section
*/
- C#(ish) style
/// Just a brief
/// A brief.
/// With a detail section
--OR--
//! Brief
//! Brief
//! With a detail section
Added some documentation for the C++-API of the FDB class. There are still some open questions linked to some of the functions.
This is a first draft.