Wording and style for Doxygen documentation

Discussion of all aspects of the game engine, including development of new and existing features.

Moderator: Forum Moderators

CrawlCycle
Posts: 27
Joined: November 20th, 2020, 5:07 am

Re: Wording and style for Doxygen documentation

Post by CrawlCycle »

This makes sense for database and computer.
But does this make sense to humans?

Code: Select all

/** Get a child by key and then by index. */
This should mean:
/** 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. */
This should mean:
/** 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.
User avatar
Pentarctagon
Project Manager
Posts: 5527
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Wording and style for Doxygen documentation

Post by Pentarctagon »

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
CrawlCycle
Posts: 27
Joined: November 20th, 2020, 5:07 am

Re: Wording and style for Doxygen documentation

Post by CrawlCycle »

Fixed that one.
User avatar
Celtic_Minstrel
Developer
Posts: 2166
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Wording and style for Doxygen documentation

Post by Celtic_Minstrel »

Both of those make sense to me. It might sound a touch awkward but not in a confusing way.
Author of The Black Cross of Aleron campaign and Default++ era.
Former maintainer of Steelhive.
CrawlCycle
Posts: 27
Joined: November 20th, 2020, 5:07 am

Re: Wording and style for Doxygen documentation

Post by CrawlCycle »

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);
CrawlCycle
Posts: 27
Joined: November 20th, 2020, 5:07 am

Re: Wording and style for Doxygen documentation

Post by CrawlCycle »

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.
 */
CrawlCycle
Posts: 27
Joined: November 20th, 2020, 5:07 am

Re: Wording and style for Doxygen documentation

Post by CrawlCycle »

Two methods to describe the time complexity of an operation.
  • 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.
I think option 2 is better.
Benchmark instead of the documentation should describe the exact timing.
User avatar
Celtic_Minstrel
Developer
Posts: 2166
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Wording and style for Doxygen documentation

Post by Celtic_Minstrel »

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.
 */
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).

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…
Author of The Black Cross of Aleron campaign and Default++ era.
Former maintainer of Steelhive.
Post Reply