Project

General

Profile

Actions
Copy link

Task #2263

open

code-style: Doxygen syntax

Added by Junxiao Shi almost 10 years ago. Updated over 5 years ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
Docs
Target version:
-
Start date:
Due date:
% Done:

0%

Estimated time:
1.00 h

Description

Add a code style rule on write Doxygen block.

This rule shall declare:

  • block style:

    /** \brief XXX
 *
 *  YYY
 */
-- vs ---
/**
 * \brief XXX
 *
 * YYY
 */

  • command style: \brief vs @brief

  • indentation

     /** \brief brief description,
  *         more brief description
  */
-- vs ---
 /** \brief brief description,
  *  more brief description
  */

  • verb usage

    • an Interest packet
    • represents an Interest packet
    • This type represents an Interest packet.

  • letter casing: \brief Represents ... vs \brief represents ...

Actions
Copy link
 #1

Updated by Junxiao Shi almost 10 years ago

  • Blocks Task #2234: Block abstraction: move constructor added
Actions
Copy link
 #2

Updated by Junxiao Shi almost 10 years ago

  • Blocks deleted (Task #2234: Block abstraction: move constructor)
Actions
Copy link
 #3

Updated by Junxiao Shi over 9 years ago

  • Description updated (diff)
  • Assignee deleted (Alex Afanasyev)
Actions
Copy link
 #4

Updated by Alex Afanasyev over 9 years ago

My preference:

  • javadoc style for commands (@brief, @param, ...)

  • Comment start on the second line

    /**
 * \brief XXX
 *
 * YYY
 */

  • Brief style and verb usage

    Brief a title or caption for a specific method (http://named-data.net/doc/ndn-cxx/current/doxygen/d5/de2/classndn_1_1SecTpm.html#afa42a8279fc065d472606677f4e1553b). This should be a complete sentence, starting with capital letter and don't really need to end with the period.

    Description of most of methods should be from the viewpoint of the user, not method: (I would call this method to) Get something, Set something, Update, ...

Actions
Copy link
 #5

Updated by Junxiao Shi over 9 years ago

I dislike some of the recommendations but I won't argue.
The purpose is consistency.

Whatever the decision is, it shall be codified as a code-style rule.
Afterwards, any touched file will be checked according to the rule, and cannot contain any violation.

Actions
Copy link
 #6

Updated by Alex Afanasyev almost 9 years ago

  • Target version changed from v0.3 to v0.5
Actions
Copy link
 #7

Updated by Davide Pesavento almost 7 years ago

  • Target version deleted (v0.5)
Actions
Copy link
 #8

Updated by Davide Pesavento over 5 years ago

We should definitely start sentences with a capital letter and have proper punctuation. I don't feel strongly about verbs in the first vs third person, and I don't care about the command leading char (@foo vs \foo).

Actions
Copy link

Also available in: Atom PDF