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.
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.
I'm new and getting into programming so I apologize if this has already been answered or explained. Basically, I've been looking in the documentation of the SFML library and come across some sf::Font class public member functions. One for example is this:
bool sf::Font::loadFromFile ( const std::string & filename )
Following that is what the function does:
/// \brief Load the font from a file
///
/// The supported font formats are: TrueType, Type 1, CFF,
/// OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.
/// Note that this function know nothing about the standard
/// fonts installed on the user's system, thus you can't
/// load them directly.
///
/// \warning SFML cannot preload all the font data in this
/// function, so the file has to remain accessible until
/// the sf::Font object loads a new font or is destroyed.
///
/// \param filename Path of the font file to load
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromMemory, loadFromStream
///
I've downloaded the library and looked inside the header files but I can't seem to find how the loadFromFile function actually accomplishes the loading (In other words, I'd be looking for a function body or a function definition that does the work). The documentation only explains what the function does, not how.
I'm sorry if this is a stupid question or something that should be apparent. I'm just extremely curious about where the core of the function is.
By the way, here is an exact link to the page and section of the documentation I'm referring to.
Thank you to anyone who answers.
The method you are looking for can be found in the public Github repository.
It's in the file Font.cpp starting on line 122:
https://github.com/SFML/SFML/blob/master/src/SFML/Graphics/Font.cpp#L122
Documentation will not mention this because the documentation is about the behavior the user of this function can rely on. How a method achieves this behavior is a private implementation detail that the user should not need to know.
I am just wondering which one is the format I have to write comments in functions so they display when hovering over the function with the mouse.
something like
void myfunct(int a; char b, float c);
This function just messes with the variables with no objective
but to show people from stack overflow what I mean.
Inputs-> a: does nothing
b: neither this one
c: nope
So when I use the functions in a big project I don't need to go looking for what was that specific function for or what was that variable's meaning.
if you think of something like C# or VB that show description of parameters and function, there is no such thing in MSVC, but Microsoft have an special format for code comments as follow that you can use for generating help:
/// <summary>
/// summary of variable, function, class or any thing else
/// </summary>
/// <remarks>
/// detailed description of object
/// </remarks>
/// <param name="a">description of a</param>
/// <param name="b">description of b</param>
/// <param name="c">description of c</param>
/// <returns>describe return value of function</returns>
when you compile your code it will generate an XML document that can be used to generate help documents.