Bugzilla – Full Text Bug Listing
| Summary: | Make auto-generated doxygen comments configurable | ||
|---|---|---|---|
| Product: | [Tools] CDT | Reporter: | Pieter Smith <pieter> |
| Component: | cdt-core | Assignee: | Marco Stornelli <marco.stornelli> |
| Status: | RESOLVED FIXED | QA Contact: | Doug Schaefer <cdtdoug> |
| Severity: | enhancement | ||
| Priority: | P3 | CC: | aegges, alexander.fedorov, Andreas.Muelder, daniel.neuberger, erankin, gonzague.reydet, jonah, kissaki, marco.stornelli, nyssen, pieter, yevshif, zorazeali |
| Version: | 8.0 | ||
| Target Milestone: | 9.11.0 | ||
| Hardware: | All | ||
| OS: | All | ||
| See Also: |
https://git.eclipse.org/r/155626 https://git.eclipse.org/c/cdt/org.eclipse.cdt.git/commit/?id=e4d544138543f86bd059dea35346182cd1d1ba63 https://git.eclipse.org/r/155872 https://git.eclipse.org/c/cdt/org.eclipse.cdt.git/commit/?id=830bf8074c1ff22436c9ae54f2c8401ec3c418a9 |
||
| Whiteboard: | |||
| Bug Depends on: | |||
| Bug Blocks: | 552334 | ||
I'm pretty sure this should be part of this bug, but the format of the block should be customizable as well. So users should be able to customize the style they're using to any of the following or evening something else:
JavaDoc style:
/**
* | <- cursor here
* @param first_parm
* @return
*/
int new_function(int first_parm) {
}
Another:
/********************************************//**
* | <- cursor here
* \param first_parm
* \return
***********************************************/
int new_function(int first_parm) {
}
Another style:
/**
| <- cursor here
@param first_parm
@return
*/
int new_function(int first_parm) {
}
Another style:
/// | <- cursor here
/// \param first_parm
/// \return
int new_function(int first_parm) {
}
Another:
/***********************************************/
/// | <- cursor here
/// @param first_parm
/// @return
///*********************************************/
int new_function(int first_parm) {
}
Details on acceptable doxygen comment styles are here http://www.stack.nl/~dimitri/doxygen/docblocks.html.
I would recommend as much flexibility as possible. At a minimum, I think have the ability to use \ instead of @ as the delimiter for starting special commands.
If this needs to be a separate bug, please let me know.
Thanks.
- Daniel
I'm working on doxygen improvement in Cdt. I plan to add several options to fine tune the behavior:
1) Use structured commands, @class, @struct and so on;
2) Use javadoc style for tags '@' or '\'
3) Use different style for enums like //< or /**< and so on
4) Use always @brief or not
5) If brief is enabled, an option for a new line or not after for detailed description
6) Generate always @pre or not
Currently CDT already support /*! or /// or /** or //! as trigger to generate doxygen documentation. With options listed above the support should be better. For the current internal architecture using a code template is not really easy. In JDT Javadoc is built-in and in the code template the user can use ${tags} but we haven't anything similar in CDT, Doxygen is just an "hook" over the management of a general multiline comment.
New Gerrit change created: https://git.eclipse.org/r/155626 (In reply to Eclipse Genie from comment #3) > New Gerrit change created: https://git.eclipse.org/r/155626 Another Gerrit is planned to further improve the https://git.eclipse.org/r/155626 *** Bug 539093 has been marked as a duplicate of this bug. *** Gerrit change https://git.eclipse.org/r/155626 was merged to [master]. Commit: http://git.eclipse.org/c/cdt/org.eclipse.cdt.git/commit/?id=e4d544138543f86bd059dea35346182cd1d1ba63 (In reply to Alexander Fedorov from comment #4) > (In reply to Eclipse Genie from comment #3) > > New Gerrit change created: https://git.eclipse.org/r/155626 > > Another Gerrit is planned to further improve the > https://git.eclipse.org/r/155626 I wait for your commit to close this bug. New Gerrit change created: https://git.eclipse.org/r/155872 (In reply to Eclipse Genie from comment #8) > New Gerrit change created: https://git.eclipse.org/r/155872 I suggest to postpone other improvements to other tickets, already created Bug 559066 and Bug 559067 . It will be good also to make preference constants private for DoxygenPreferences class - actually they are a part of implementation and should not be exposed to the clients. Gerrit change https://git.eclipse.org/r/155872 was merged to [master]. Commit: http://git.eclipse.org/c/cdt/org.eclipse.cdt.git/commit/?id=830bf8074c1ff22436c9ae54f2c8401ec3c418a9 According to Alexander's comment, I close this bug. Other problems about Doxygen support is already tracked by other bug reports. Thanks to Alexander for all the support. |
Build Identifier: 20100917-0705 Make auto-generated doxygen templates configurable (E.g. under C/C++ -> Code Style -> Code Templates) Eclipse auto-generates the following comment block when typing /** for example: /** * | <- cursor here * @param first_parm * @return */ int new_function(int first_parm) { } Ideally the generated block should be fully customizable for all comment block types so that the following can be generated: /** * <Mandatory: Describe in 1 sentence> <- text pre-selected * <Optional: Detail description or omit> * @pre <Mandatory: Describe or '-' if none> * @param[in,out] first_parm <Optional: Describe or omit> * @return <Mandatory: Describe> */ int new_function(int first_parm) { } Minimally, the mandatory doxygen commands should be specifiable for all comment block types: /** * | <- cursor here * @pre * @param[in,out] first_parm * @return */ int new_function(int first_parm) { } NOTE: This is NOT a duplicate of Bug 238764, where Thomas Gern only requested c++-Style comments to be added. Reproducible: Always