I have some code which I want to document with in-body comments like so:
/*! \file best.cpp
* \brief The best
*
* I am the best
*/
/*! \fn void theBestFunction(int)
* I'm the best blah blah blah
*/
void theBestFunction(int ever)
{
doThings();
/*!
* Does some more things
*/
doMoreThings();
/*!
* Checks that the things it does are the best
*/
checkBest();
}
But when I run doxygen on this it seems to format the inside blocks into code fragments, as if the #code or \code commands were used (which they were not). I would like the in-body comments to be formatted like normal text.
Has anybody encountered this before? Thanks.
I managed to fix the problem. It turns out that somehow Doxygen was processing those blocks as being indented with respect to each other, and indentation in Markdown (much like on StackOverflow) indicates a code block (http://en.wikipedia.org/wiki/Markdown#Code). I simply turned off Markdown and fixed the issue.
For anybody reading this question in the future, if you still want Markdown support, be careful not to start comment blocks on the 2nd line -- start comments right away.
Changing my minimal example to this:
/*! \fn void theBestFunction(int)
* I'm the best blah blah blah
*/
void theBestFunction(int ever)
{
doThings();
/*! Does some more things
*/
doMoreThings();
/*! Checks that the things it does are the best
*/
checkBest();
}
(note the start of the in-body comments immediately, as opposed to a blank line first) solves the issue.
Related
I found, in eclipse,
/*
* Hello world, this is green.
*
*/
The comments will be green. However,
/**
* Hello moon, this is blue.
*
*/
If I use /**, it will become blue.
So why? Any difference?
While /* starts a regular multi-line comment, /** starts a multi-line comment supporting the javadoc tool, which generates HTML documentation from your comments.
This is an example from the documentation:
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {#link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* #param url an absolute URL giving the base location of the image
* #param name the location of the image, relative to the url argument
* #return the image at the specified URL
* #see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
The Java API specification itself is an example of HTML documentation generated through javadoc.
Comments starting with /* are normal code comments. These are generally used on top of a code line to describe the logic.
Comments starting with /** are used for javadocs. These are used on top of methods and classes
/* is just a multiline comment.
/** is for Javadoc, which allow you to make a doc more readable for users.
Take a look
Javadoc
While the /** comment starter is for javadoc, technically they are actually the same from the compilers point of view. A comment is a comment is a comment. The important part here is that /** is /* with an extra asterisk added.
/* text */: The compiler ignores everything from /* to */
/** documentation */:
This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of comment, just like it ignores comments that use /* and */. The JDK javadoc tool uses doc comments when preparing automatically generated documentation. For more information on javadoc, see the Java tool documentation
My doxygen for the following code shows up like this:
Spawns two mettaurs on the fieldMay optionally spawn an empty tile for challenge
Where the brief description should be. Notice it's merging the brief and the detailed description.
/*! \brief Spawns two mettaurs on the field
* \class TwoMettaurMob
*
* May optionally spawn an empty tile for challenge
*/
#pragma once
#include "bnMobFactory.h"
#include "bnMettaur.h"
#include "bnMettaurIdleState.h"
class TwoMettaurMob :
public MobFactory
{
public:
TwoMettaurMob(Field* field);
~TwoMettaurMob();
/**
* #brief Builds and returns the mob
* #return Mob pointer. must be deleted manually.
*/
Mob* Build();
};
I'm following doxygen's example for doc blocks:
/*! \brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/
Anyone know a solution?
I could reproduce the problem with the current (1.8.15) version of doxygen.
The solution of #Someprogrammerdude does work
The order of commands is a bit strange I would have expected first the \class followed by the \brief description, also the \class is not necessary as the documentation is (in this case) directly in front of the class.
Another solution is to place a . at the end of the sentence and have JAVADOC_AUTOBRIEF or QT_AUTOBRIEF set to YES.
The background of the problem is that \class is not seen as a ending the \brief documentation. It might be worthwhile to submit an issue report at https://github.com/doxygen/doxygen/issues/new (so either it can be fixed or some extra objections can be given against using \class, and others with similar meaning, for terminating a brief description.
I intend to include some documented C++ classes (let say AClass) within a Doxygen group (let say GROUP_C), while that group is into another one (let say GROUP_B), and that second group into another, base one (let say GROUP_A). Like this:
/** \addtogroup GROUP_A */
/** #{ */
/** \defgroup GROUP_B */
/** #{ */
/** \defgroup GROUP_C */
/** #{ */
/// Comment
class AClass
{
};
/** #} */
/** #} */
/** #} */
I'm trying to get a clean and logical documentation for that situation, but, as simple as I see it, I have not been able to found anything more specific than the Doxygen official documentation, where nothing is said about any cyclical grouping problems. However, just doxygen-ing the simple code above, such problems occur:
warning: Refusing to add group GROUP_C to group GROUP_B, since the latter is already a subgroup of the former
I also get strange breadcrumbs indications of the generated module under the AClass documentation:
Does anybody know what am I understanding wrong in the nesting-group system of Doxygen?
Thanks in advance!
This solution has been working for me for many years since old versions of Doxygen:
/** \defgroup GROUP_A My top-level group description
*
* Put here a longer description.
*
**/
/** #addtogroup GROUP_B My group B description
* \ingroup GROUP_A
* #{ */
// classes, etc.
/** #} */
/** #addtogroup GROUP_C My group C description
* \ingroup GROUP_B
* #{ */
// classes, etc.
/** #} */
Unfortunately your given example works as expected on doxygen-1.8.8 and on latest master git branch. The warning does not appear.
Is it possible you are including other source files (than the presented example code) into your test run and that other files contain conflicting \defgroup or \addgroup statements that cause the circles in the group structure?
Regarding that "GROUP_A" doubling line below "AClass Class Reference" - I guess that is simply a doxygen bug.
I'm having trouble getting my clang-format to quite cooperate with multi-line comments. I have tried:
CodePragmas: '^[^ ]'
But this still results in the following. Before formatting:
class Test
{
/* =======
* Public Functions
* ======== */
public:
};
After formatting:
class Test
{
/* =======
* Public Functions
* ======== */
public:
};
Any help would be greatly appreciated. Thanks.
I have a slightly different comment format, but same situation. If you know the format of your block comments all use the same pattern, I think something like this will work:
CommentPragmas: '/\* =======\n((.+\n.+)+)======== \*/'
If you want to exclude all multi-line block comments, I think this will work:
CommentPragmas: '/\*(.+\n.+)+\*/'
I found that the ColumnLimit still applies to those comments, causing them to wrap in undesirable ways. Otherwise, clang-format (3.8) leaves those blocks untouched.
I am using the vim plugin DoxygenToolkit that is pretty cool.
by highlighting a function and calling :Dox it setup a doxygen comment like below.
/// #brief
///
/// #param id
///
/// #return
int32_t printme(int32_t it)
Is there any setting in this tool that prevent to prepare only the #brief section without showing the #return and #param ones?
I tried by setting thse 2 parameters, but I cam see that the argument of the function is still printed out together with many lines.
let g:DoxygenToolkit_paramTag_pre=""
let g:DoxygenToolkit_returnTag=""
/// #brief
///
/// id
///
///
int32_t printme(int32_t it)
I know this is not the plugin you are using, but anyway, with lh-cpp (:DOX command), you would be able to override the doxygen-function snippet and keep/remove/change whatever you wish. The plugin takes care of detecting everything that can be detected, the snippet formats them.