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.
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
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.
Looking through the C and C++ domains of Sphinx, it doesn't appear to have native support for documenting enums (and much less anonymous enums). As of now, I use cpp:type:: for the enum type, and then a list of all possible values and their description, but that doesn't seem like an ideal way to deal with it, especially since it makes referencing certain values a pain (either I reference just the type, or add an extra marker in front of the value).
Is there a better way to do this? And how would I go about handling anonymous enums?
A project on Github, spdylay, seems to have an approach. One of the header files at
https://github.com/tatsuhiro-t/spdylay/blob/master/lib/includes/spdylay/spdylay.h
has code like this:
/**
* #enum
* Error codes used in the Spdylay library.
*/
typedef enum {
/**
* Invalid argument passed.
*/
SPDYLAY_ERR_INVALID_ARGUMENT = -501,
/**
* Zlib error.
*/
SPDYLAY_ERR_ZLIB = -502,
} spdylay_error;
There some description of how they're doing it at https://github.com/tatsuhiro-t/spdylay/tree/master/doc, which includes using a API generator called mkapiref.py, available at
https://github.com/tatsuhiro-t/spdylay/blob/master/doc/mkapiref.py
The RST it generates for this example is
.. type:: spdylay_error
Error codes used in the Spdylay library.
.. macro:: SPDYLAY_ERR_INVALID_ARGUMENT
(``-501``)
Invalid argument passed.
.. macro:: SPDYLAY_ERR_ZLIB
(``-502``)
Zlib error.
You could take a look and see if it's useful for you.
Sphinx now has support for enums
Here is an example with enum values:
.. enum-class:: partition_affinity_domain
.. enumerator:: \
not_applicable
numa
L4_cache
L3_cache
L2_cache
L1_cache
next_partitionab
Hi Maybe you should consider using doxygen for documentation as it has a lot more native support for c / c++. if you want to retain the sphinx output of your documentation you can output from doxygen as xml, then using Breathe it will take the xml and give you the same sphinx output you are used to having.
Here is an example of documenting an enum in doxygen format from the breathe website.
//! Our toolset
/*! The various tools we can opt to use to crack this particular nut */
enum Tool
{
kHammer = 0, //!< What? It does the job
kNutCrackers, //!< Boring
kNinjaThrowingStars //!< Stealthy
};
hope this helps.
When I create a method comment in Netbeans by typing /** + ENTER I get something like this
/**
*
* #param nameOfParam
* #return
* #throws SQLException
*/
but in my case I like comments looking like this
/**
*
* #param
* nameOfParam -
* #return
* #throws SQLException
*/
So I need to change this template but I can't find where. I can change every single behavior of Netbeans besides this one.
Can somebody help?
Method comment templates cannot be customized to the level which is expected in this question. These customization features can be added to the NetBeans IDE and there is a specific way how this can be done as the NetBeans IDE is an open source project working in open source way of development. The typical steps to ask the developers to add this feature in NetBeans IDE will be
Log an enhancement request [RFE] in the NetBeans IDE issue tracker
Notify the community about your RFE by writing mail to the NetBeans IDE users mailing list (users) and asking all to vote for your request
According to the votes the RFE will get lined up for development in the next release cycle.