Wording and style for Doxygen documentation
Moderator: Forum Moderators
-
- Posts: 27
- Joined: November 20th, 2020, 5:07 am
Re: Wording and style for Doxygen documentation
This makes sense for database and computer.
But does this make sense to humans?
This should mean:
similar to:
https://stackoverflow.com/questions/14941366
Another issues is that I can't describe getting the first child with a similar phrase yet.
This should mean:
I guess I will just leave this one as is.
But does this make sense to humans?
Code: Select all
/** Get a child by key and then by index. */
/** Get all children with the key. Among those children, pick one by index. */
similar to:
https://stackoverflow.com/questions/14941366
--♦--
Another issues is that I can't describe getting the first child with a similar phrase yet.
Code: Select all
/** Get the first child with the key. */
/** Get all children with the key. Among those children, pick the first one. */
I guess I will just leave this one as is.
Last edited by CrawlCycle on November 22nd, 2020, 9:21 pm, edited 3 times in total.
- Pentarctagon
- Project Manager
- Posts: 5599
- Joined: March 22nd, 2009, 10:50 pm
- Location: Earth (occasionally)
Re: Wording and style for Doxygen documentation
For
/** Get the first children with the key. */
, if the method returns one child (singular) but the comment says it gets children (plural), then I'd say the comment is just incorrect.99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
take one down, patch it around
-2,147,483,648 little bugs in the code
-
- Posts: 27
- Joined: November 20th, 2020, 5:07 am
Re: Wording and style for Doxygen documentation
Fixed that one.
- Celtic_Minstrel
- Developer
- Posts: 2290
- Joined: August 3rd, 2012, 11:26 pm
- Location: Canada
- Contact:
Re: Wording and style for Doxygen documentation
Both of those make sense to me. It might sound a touch awkward but not in a confusing way.
-
- Posts: 27
- Joined: November 20th, 2020, 5:07 am
Re: Wording and style for Doxygen documentation
I think this is good:
Code: Select all
/**
* Get the first node in the list of children with the key.
* Return the empty node singleton if we can't find such a node.
* @see child(config_key_type, int)
*/
const config & child_or_empty(config_key_type key) const;
/**
* Get a node in the list of children with the key.
* Return the static invalid node if we can't find such a node.
* @param key The key.
* @param n The index of the node in the list.
* @note A negative @a n accesses from the end of the object.
* @example child("apple", -1) is the last child with the key "apple"
* @see child_or_empty(config_key_type)
*/
config &child(config_key_type key, int n = 0);
-
- Posts: 27
- Joined: November 20th, 2020, 5:07 am
Re: Wording and style for Doxygen documentation
Even better:
The "list of children" is an implementation detail.
The "list of children" is an implementation detail.
Code: Select all
/** Get the first child node with the key. ... */
/** Get a child node with the key. ... */
/**
* Append an empty child node with @p key. The new child will be the last
* one in the list of children with the @p key.
*/
-
- Posts: 27
- Joined: November 20th, 2020, 5:07 am
Re: Wording and style for Doxygen documentation
Two methods to describe the time complexity of an operation.
Benchmark instead of the documentation should describe the exact timing.
- Hint the speed of the operation with another set of verbs in the brief description:
For example, create vs fabricate, get vs retrieve - Document the time complexity as a new section in the Doxygen block.
Benchmark instead of the documentation should describe the exact timing.
- Celtic_Minstrel
- Developer
- Posts: 2290
- Joined: August 3rd, 2012, 11:26 pm
- Location: Canada
- Contact:
Re: Wording and style for Doxygen documentation
I think the use of the word "key" here is actually wrong. In WML, I think we usually use "tag" when referring to child nodes and reserve "key" for attributes (key-value pairs).CrawlCycle wrote: ↑November 26th, 2020, 6:47 am Even better:
The "list of children" is an implementation detail.Code: Select all
/** Get the first child node with the key. ... */ /** Get a child node with the key. ... */ /** * Append an empty child node with @p key. The new child will be the last * one in the list of children with the @p key. */
Conceptually, WML nodes are ordered without respect to the key/tag, so I don't think you need to mention the "list of children". If you do want to mention it you could drop the "with the @p key" part - it's still true, as it will be last in the child order as well.
Regarding complexity: I don't think we need to specify things like O(n) or anything, but explicitly mentioning stuff about complexity can't hurt. Actually, changing the verb as well doesn't seem like a terrible idea…