You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@mesos.apache.org by "Bernd Mathiske (JIRA)" <ji...@apache.org> on 2015/06/02 17:38:24 UTC
[jira] [Comment Edited] (MESOS-2501) Doxygen style for libprocess
[ https://issues.apache.org/jira/browse/MESOS-2501?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14569266#comment-14569266 ]
Bernd Mathiske edited comment on MESOS-2501 at 6/2/15 3:38 PM:
---------------------------------------------------------------
Proposal: let's use the JavaDoc style for code comments that are intended as Doxygen input. And let's keep the "//" style for everything else. Reasons:
- It is clear what is "exported" documentation vs. "internal" commenting. Otherwise one could easily overlook something one way or the other.
- Especially while incrementally making doxygen comments to existing code, we can easily spot what has already been doxygenized and what has not.
- Alternatives to the JavaDoc style where considered, and they look harder to read. But that's debatable. So, see for yourselves: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#cppblock
Here is a quick rundown by example of the main alternative styles. Note that the (more or less) blank lines before and after the details part are optional (i.e. TBD).
JavaDoc style:
```
/**
* Returns 'prefix(N)' where N represents the number of instances
* where the same prefix (wrt. string value equality) has been used
* to generate an ID.
*
* More details if any would appear here.
*
* @param prefix The prefix to base the result.
* @return An "ID" in the shape 'prefix(N)'.
*/
std::string generate(const std::string& prefix = "");
```
Qt style 1:
```
//! Returns 'prefix(N)' where N represents the number of instances
// where the same prefix (wrt. string value equality) has been used
// to generate an ID.
/*! More details if any would appear here.
\param prefix The prefix to base the result.
\return An "ID" in the shape 'prefix(N)'.
*/
std::string generate(const std::string& prefix = "");
```
Qt style 2:
```
/*! Returns 'prefix(N)' where N represents the number of instances
* where the same prefix (wrt. string value equality) has been used
* to generate an ID.
*
* More details if any would appear here.
*
* \param prefix The prefix to base the result.
* \return An "ID" in the shape 'prefix(N)'.
*/
std::string generate(const std::string& prefix = "");
```
Triple-slash style:
```
/// Returns 'prefix(N)' where N represents the number of instances
/// where the same prefix (wrt. string value equality) has been used
/// to generate an ID.
///
/// More details if any would appear here.
///
/// \param prefix The prefix to base the result.
/// \return An "ID" in the shape 'prefix(N)'.
std::string generate(const std::string& prefix = "");
```
Double-slash-and-bang style:
```
//! Returns 'prefix(N)' where N represents the number of instances
//! where the same prefix (wrt. string value equality) has been used
//! to generate an ID.
//!
//! More details if any would appear here.
//!
//! \param prefix The prefix to base the result.
//! \return An "ID" in the shape 'prefix(N)'.
std::string generate(const std::string& prefix = "");
```
And there are so many more! You can mix and match. I suggest we settle on one simple style that's easy to spot and familiar. For me, that would be either JavaDoc or Triple-Slash. The latter looks pretty good, too, but it has these disadvantages:
- It is harder to spot what is already in doxygen format, especially in large files.
- The "// \param" combination does not stand out as much as "* @param".
OK, the latter can be fixed. How does this look?
```
/// Returns 'prefix(N)' where N represents the number of instances
/// where the same prefix (wrt. string value equality) has been used
/// to generate an ID.
///
/// More details if any would appear here.
///
/// @param prefix The prefix to base the result.
/// @return An "ID" in the shape 'prefix(N)'.
std::string generate(const std::string& prefix = "");
```
Still, JavaDoc has my vote :-)
was (Author: bernd-mesos):
Proposal: let's use the JavaDoc style for code comments that are intended as Doxygen input. And let's keep the "//" style for everything else. Reasons:
- It is clear what is "exported" documentation vs. "internal" commenting. Otherwise one could easily overlook something one way or the other.
- Especially while incrementally making doxygen comments to existing code, we can easily spot what has already been doxygenized and what has not.
- Alternatives to the JavaDoc style where considered, and they look harder to read. But that's debatable. So, see for yourselves: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#cppblock
Here is a quick rundown by example of the main alternative styles. Note that the (more or less) blank lines before and after the details part are optional (i.e. TBD).
JavaDoc style:
/**
* Returns 'prefix(N)' where N represents the number of instances
* where the same prefix (wrt. string value equality) has been used
* to generate an ID.
*
* More details if any would appear here.
*
* @param prefix The prefix to base the result.
* @return An "ID" in the shape 'prefix(N)'.
*/
std::string generate(const std::string& prefix = "");
Qt style 1:
//! Returns 'prefix(N)' where N represents the number of instances
// where the same prefix (wrt. string value equality) has been used
// to generate an ID.
/*! More details if any would appear here.
\param prefix The prefix to base the result.
\return An "ID" in the shape 'prefix(N)'.
*/
std::string generate(const std::string& prefix = "");
Qt style 2:
/*! Returns 'prefix(N)' where N represents the number of instances
* where the same prefix (wrt. string value equality) has been used
* to generate an ID.
*
* More details if any would appear here.
*
* \param prefix The prefix to base the result.
* \return An "ID" in the shape 'prefix(N)'.
*/
std::string generate(const std::string& prefix = "");
Triple-slash style:
/// Returns 'prefix(N)' where N represents the number of instances
/// where the same prefix (wrt. string value equality) has been used
/// to generate an ID.
///
/// More details if any would appear here.
///
/// \param prefix The prefix to base the result.
/// \return An "ID" in the shape 'prefix(N)'.
std::string generate(const std::string& prefix = "");
Double-slash-and-bang style:
//! Returns 'prefix(N)' where N represents the number of instances
//! where the same prefix (wrt. string value equality) has been used
//! to generate an ID.
//!
//! More details if any would appear here.
//!
//! \param prefix The prefix to base the result.
//! \return An "ID" in the shape 'prefix(N)'.
std::string generate(const std::string& prefix = "");
And there are so many more! You can mix and match. I suggest we settle on one simple style that's easy to spot and familiar. For me, that would be either JavaDoc or Triple-Slash. The latter looks pretty good, too, but it has these disadvantages:
- It is harder to spot what is already in doxygen format, especially in large files.
- The "// \param" combination does not stand out as much as "* @param".
OK, the latter can be fixed. How does this look?
/// Returns 'prefix(N)' where N represents the number of instances
/// where the same prefix (wrt. string value equality) has been used
/// to generate an ID.
///
/// More details if any would appear here.
///
/// @param prefix The prefix to base the result.
/// @return An "ID" in the shape 'prefix(N)'.
std::string generate(const std::string& prefix = "");
Still, JavaDoc has my vote :-)
> Doxygen style for libprocess
> ----------------------------
>
> Key: MESOS-2501
> URL: https://issues.apache.org/jira/browse/MESOS-2501
> Project: Mesos
> Issue Type: Documentation
> Components: libprocess
> Reporter: Bernd Mathiske
> Assignee: Bernd Mathiske
> Original Estimate: 7m
> Remaining Estimate: 7m
>
> Create a description of the Doxygen style to use for libprocess documentation.
> It is expected that this will later also become the Doxygen style for stout and Mesos, but we are working on libprocess only for now.
> Possible outcome: a file named docs/doxygen-style.md
> We hope for much input and expect a lot of discussion!
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)