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
Related
I have seen this doc formatting comment in a library I added to one of my workspaces, and I see it uses something close to doxygen, and it works great off the shelf with VS code, I didn't install doxygen or any other doc generator plug in
/**********************************************************************/
/*!
#brief Apply the bracket's calibration curve to get a load in N from signal in mV
#param mV_reading The loadcell's input signal in mV
*/
/**********************************************************************/
float _getTorqueNmFromBracketCurve(float mV_reading);
It works super well and generates nice doc when dragging over the function
Can someone point me to what is this doc and where I can find it's syntax documentation / arguments to learn to use it?
Thanks!
Visual Studio and Visual Studio Code recognize Doxygen comment formatting.
/**, /*! as well as ///-style comments are supported.
There are also extensions that can generate doxygen comments.
There are only some syntaxes that can be parsed by VSCode.
Reference: article by MS C++ Team: C++ Team Blog - Visual Studio Code C++ Extension July 2020 Update: Doxygen comments and Logpoints
/// #brief Calculates the area of the triangle
/// #tparam T is the template param
/// #param base is the horizontal length
/// #param height is the vertical length
/// #return Area of triangle
/// #deprecated This is the deprecated comment
template<typename T>
T TriangleAream(T base, T height)
{
double result;
result = base * height * 0.5;
return (T)result;
}
imgur - doxygen VSCode visual picture
There are lots of things VS C++ team can do.
Like:
GitHub issue - Can't specify newline
GitHub issue - Customizable Doxygen tags for Quick Info
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 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.
Does NetBeans have C auto comment?
I installed NetBeans IDE 7.2.1 and C/C++ Plugins.
When I type in "/**" and press Enter, it automatically generate some code like bellow.
/**
* #param param1
* #param param2
* #param param3
*/
I'm just wondering if I can modify what it generate.
I want to add more info like author, date, remark.
Simply saying, I want some comment to be generated when I type in "/**" and press Enter like bellow.
(The function is already defined.)
/**
* #author
* #date
* #param param1
* #param param2
* #param param3
* #remark
*/
void do_something( struct sturct_one *param1, int param2, char *param3 )
{
...
}
Please help me.
Jan,
the NetBeans IDE documentation section on adding source code documentation does not mention the possibility to customize the Doxygen template. So a short answer to your question
I'm just wondering if I can modify what it generate
is: no, you can't.
Typically, one does not need any extras, e.g. the tags #author and #date from your example are unnecessary if you use a version control system. Did you considered using a CVS?
As an alternative solution (though not as elegant as typing '/**') you could use code templates. As described in the NetBeans documentation, you can define abbreviations for code templates. In your case you could define templates for Doxygen comments with #author, #date, #remark tags and 1, 2, 3, ... parameters, and use abbreviations 1, 2, ... to quickly insert the comments.
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.