Add Doxygen \memberof annotations
#3027
Conversation
amomchilov
force-pushed
the
amomchilov/memberof
branch
2 times, most recently
from
529652b
to
ba6d3b5
Compare
include/prism.h
Outdated
| @@ -43,6 +43,7 @@ | |||
| * The prism version and the serialization format. | |||
| * | |||
| * @returns The prism version as a constant string. | |||
| * \public \memberof pm_parser | |||
There was a problem hiding this comment.
I would prefer that this not be a member of parser, since it does not accept it as a parameter/doesn't correspond to a parser.
| */ | ||
| PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse(pm_parser_t *parser); | ||
|
|
||
| /** | ||
| * This function is used in pm_parse_stream to retrieve a line of input from a | ||
| * This function is used in pm_parse_stream() to retrieve a line of input from a |
There was a problem hiding this comment.
| * This function is used in pm_parse_stream() to retrieve a line of input from a | |
| * This function is used in pm_parse_stream to retrieve a line of input from a |
There was a problem hiding this comment.
The () makes this into link to the pm_parse_stream() function that uses this callback.
| * stream. It closely mirrors that of fgets so that fgets can be used as the | ||
| * default implementation. | ||
| * \public \memberof pm_parser |
There was a problem hiding this comment.
This shouldn't be marked as a member of parser, as it's a user-defined callback that does not correspond to a parser.
There was a problem hiding this comment.
It's still strongly related to the parser (similar to a type alias or nested interface defined in a Ruby class), and renders nicely on the same page under "Public types":
WDYT?
include/prism/node.h
Outdated
| @@ -112,6 +118,7 @@ PRISM_EXPORTED_FUNCTION const char * pm_node_type_to_str(pm_node_type_t node_typ | |||
| * @param node The root node to start visiting from. | |||
| * @param visitor The callback to call for each node in the subtree. | |||
| * @param data An opaque pointer that is passed to the visitor callback. | |||
| * \public \memberof pm_node | |||
There was a problem hiding this comment.
This one I disagree with, as it's more related to the visitor (the function callback). So I would exclude this.
There was a problem hiding this comment.
What do you think about switching it to "related"?
It'll still help discoverability, since someone looking at this API would probably look in pm_node to start
include/prism/node.h
Outdated
| @@ -123,6 +130,7 @@ PRISM_EXPORTED_FUNCTION void pm_visit_node(const pm_node_t *node, bool (*visitor | |||
| * @param node The node to visit the children of. | |||
| * @param visitor The callback to call for each child node. | |||
| * @param data An opaque pointer that is passed to the visitor callback. | |||
| * \public \memberof pm_node | |||
There was a problem hiding this comment.
Same here, this is more related to the visitor, so I don't think this should be associated with a particular node.
amomchilov
force-pushed
the
amomchilov/memberof
branch
2 times, most recently
from
6f947bd
to
3f77637
Compare
amomchilov
force-pushed
the
amomchilov/memberof
branch
from
3f77637
to
63f4205
Compare
|
@kddnewton Ready for re-review |
Doxygen's
\memberofcommand lets you associate C functions to types, to make them render as if they were actual methods. This is in a similar spirit to\extends, which we use to simulate inheritance frompm_node.Demo:
It's possible to hide the
PRISM_EXPORTED_FUNCTIONmacro spam from these return types, but I'll do that in a separate PR.