Bug #9442: Doxygen comments in @defgroup are not part of generated doc - Ceph - Ceph

Actions

Copy link

Bug #9442

closed

Doxygen comments in @defgroup are not part of generated doc

Added by David Zafman over 9 years ago. Updated almost 9 years ago.

Status:

Resolved

Priority:

Normal

Assignee:

Kefu Chai

Category:

librados

Target version:

% Done:

100%

Source:

other

Tags:

Backport:

Regression:

Severity:

3 - minor

Reviewed:

Affected Versions:

ceph-qa-suite:

Pull request ID:

Crash signature (v1):

Crash signature (v2):

Description

Large sections of comments in the librados.h specified to describe a grouping with @defgroup are not part of the generated doc.

For example:

/**
 * @defgroup librados_h_snaps Snapshots
 *
 * RADOS snapshots are based upon sequence numbers that form a
 * snapshot context. They are pool-specific. The snapshot context
...

Actions

Copy link

Updated by Loïc Dachary almost 9 years ago

Description updated (diff)
Regression set to No

Actions

Copy link

Updated by Loïc Dachary almost 9 years ago

Status changed from New to 12
Assignee set to Kefu Chai

Kefu, would you happen to know why we loose these good chunks of documentation ?

Actions

Copy link

Updated by Greg Farnum almost 9 years ago

Assignee changed from Kefu Chai to Josh Durgin

We're using some comment notation that isn't supported by our toolchain; I'm not sure if this issue is part of that or not. Josh knows what those pieces are, having written the librados docs and helped set up the tooling.

Actions

Copy link

Updated by Josh Durgin almost 9 years ago

Assignee deleted (~~Josh Durgin~~)

It's an issue with the component translating doxygen's xml output to sphinx markup. Neither of the tools that do this support the defgroup section apparently. (iirc Kefu changed us from tv's custom asphyxiate tool to breathe not long ago). Making one of those tools understand this would be ideal imo.

Actions

Copy link