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
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
Is there a way to make visual studio automatically place the doxygen tags in a C++ source file ?
What I mean is for example this piece of code:
int foo(bool p);
If I type /// on top of it, Visual Studio automatically generates the following lines:
/// <summary>
///
/// </summary>
/// <param name="p"></param>
/// <returns></returns>
int foo(bool p);
My question is: is it possible to do the same with doxygen (when I type /**)? To make VS generate the following:
/**
* #brief
* #param p
* #return
*/
int foo(bool p)
My question is about writing the documentation tags (not generating the final doxygen).
There is a setting in VS19 that does just that:
Tools > Options > Text Editor > C/C++ > CodeStyle > General > Generated documentation comments style
Set this to Doxygen (/**)
I don't know why this did not pop out on my search on Visual Studio Marketplace, but this does the job using /*! doxygen tag.
https://marketplace.visualstudio.com/items?itemName=dragospop.CppDoxyComplete
Example:
/*!
*
*
* \param b
* \return
*/
int foo(bool b)
I don't know why this did not pop out on my search on Visual Studio Marketplace
For the VS2019 and VS2022 version there is another extension based on the CppDoxyCompletion, but with a few more features.
I am sure this is something silly I've done but I can't see what it is:
So I have c++ project which has a main.cpp file and some classes. It was not written with doxygen in mind (error #1) but I'm looking to correct my mistake and generate some documentation. So I installed doxygen and ran the doxygen GUI, entered the project name/synopsis and specified the source and destination locations.
Also to get some output above a function I added a comment in the style the doxygen spec requires:
//! My actual function doesn't really look like this
/*!
* Some sample detail which isn't exactly the same as the main
* function but the structure is the same
*/
void sampleFunction()
{
doSomethingUninteresting();
}
However when I hit run in doxywizard no extra comments are made.
If I set the extraction mode to documented entities only main.cpp doesn't even show up. If I set it to all entities main.cpp appears under files and the function is in there however there is no detail whatsoever in the file.
As a complete novice trying to retrofit my project no doubt I've omitted to do something important but all the documentation/tutorials I've read don't suggest anything other than what I've stated needs to be done so I turn to the knowledgeable SO community for assistance
UPDATE:
In response to the comment by Arne Mertz here are a few more details:
Doxywizard is in Program Files/doxygen/bin and the config file is wherever doxywizard creates it by default
My source code is in User/Desktop/
The output folder is in User/Desktop/Documentation
To document a global functions you have also to include a file name. E.g.
/*!
* \file MyFileName.cpp
* \brief a brief description of a file
*/
//! My actual function doesn't really look like this
/*!
* Some sample detail which isn't exactly the same as the main
* function but the structure is the same
*/
void sampleFunction()
{
doSomethingUninteresting();
}
Note, that the name after \file keyword should be exactly as the name of the file.
I was being foolish as I suspected, to be safe I'd made a copy of my project and so the version I was editing was not the version being interpreted by doxygen
I apologise to anyone who wasted their time trying to help with this but I very much appreciate your attempts to do so :)
In my years at college I've learned to program Java, which I did in Eclipse. I loved the feature in Eclipse on how Javadoc comments were able to pop-up in a window. At the moment I'm programming C++ and I'm really starting to miss this feature.
That's why I'm asking: is there a plug-in of something that acchieves the same result. Currently I am programming c++ with Visual Studio Express 2010, that does not have anything like this except for showing a function interface in the auto completion window. I would like to read more info such as reading up on pre- and postconditions for example, either for code from existing libraries (if they exist) or otherwise only for code I wrote myself.
Now I know of Doxygen, but that it not really what I'm looking for. It is a good enough fall back mechanism, but I really like to have it readily available from the same window I'm writing my code in.
Does something like this exist for Visual Studio? Or can I start using the C++ version of Eclipse and run the Javadoc generator there (I actually haven't tried this!) to get those nice pop-up comments?
EDIT:
I've been trying to get XML style comments working, but something like:
/// <summary>This constructor takes parameters to set the
/// members of the Cow class.
/// <param name="ho">Hobby as string of the cow.</param>
/// <param name="wt">Weight of the cow as a double.</param>
/// </summary>
Cow(const char * nm, double wt);
still only gives me the string "Cow(const char * nm, double wt)" in the pop-up window. Built with the \doc option, I do have a .xml file generated (in my Debug folder).
In C# you can write
///
And it will generate a XML style comment like:
/// <summary>
///
/// </summary>
/// <param name="parameter"> </param>
/// <returns> </returns>
You can let Visual Studio generate an XML file, which can be processed to get something like javadoc. I'm 100% sure it works on C#, but it seems that C++ uses a different style. If I go to project options > Configuration Options > XML Document Generator > General, and set the "Validate IntelliSense" to Yes, you can place comments in your .h file:
class Test {
public:
// The constructor
Test(void);
// The destructor
~Test(void);
// The function description
void Function();
};
If I go to my main.cpp, and type this:
Test * test = new Test();
test->
As soon as I hit the '>', a box pops up with a list of functions (destructor and the function in this case). If I select Function for example, a tooltip pops up with "The function description":
void Test::Function();
The function description
File: test.h
I'm not sure if there are any plugins, but I hope I helped you a bit here!
If you have CodeRush/Refactor you can try the CR_Documenter plugin (use VS Extension Manager). It provides a new dockable window with such documentation.
I am with you - Eclipse is so much better for viewing documentation.
Use SandCastle to integrate with the builtin help (F1). Its not as good as inline help like you get in Eclipse, but you can hover over a type, press F1 and then you are there.
To do this, install Sandcastle and Sandcastle Help File Builder. Then in your Sandcastle Help File Builder project, make sure to tick the box for MSHelpViewer. This will generate documentation and a script you can run to integrate your custom documentation into the F1 help.
I'm programming in C++ using Visual Studio 2010 Ultimate. I want to document some functions and I want the documentation to show up in Intellisense.
According to MSDN, I just need to put the comment before the declaration or after it on the same line. So I tried this:
// This is a test.
void foo();
void bar() { foo(); }
When moving my mouse over foo(), the comment doesn't appear in the tooltip. I also tried:
///
<summary></summary> tags
Building with /doc (by setting the "Generate XML documentation files" option in the project settings)
I've had no luck so far. Does anyone know a way to make this work?
This now supported in VS 2012!
Previously, XML tags in the comments were only read in by C++/CLI, not plain old C++.
VS 2012 now brings at least some of this into regular C++ - it is in the What's New in Visual Studio 2012 and in the MSDN docs: XML Documentation (Visual C++).
I've tested it with my own application in 2012 ultimate, and I can confirm that the summary, para, and seealso tags are all pulled out an formatted for tooltips.
I'm not sure which version of Visual Studio introduced that but in VS 2015 you can simply put comment above a function, method, class, struct, union, enum class, namespace or even individual variables (locals too) and it will be shown by Intellisense. If you want to document something from a different module, you have to write a comment in the header file. Examples:
Try installing Visual Assist and using doxygen style:
/**
* COMMENT DESCRIBING A CLASS
**/
class Foo
{
public:
/**
* \brief A foo method.
*
* More complete description of foo.
*
* \param i A foo parameter.
* \return An int
*
**/
int fooMethod(int i);
private:
int i; /*!< COMENT OF A MEMBER */
};
I haven't used VS2010 is too many years to remember whether this worked there or not. But what I have done for years in many different version of VS is ...:
#pragma region foo(float)
/// <summary> .... </summary>
/// <param name="bar"> .... </param>
/// <returns> .... </returns>
int foo(float bar)
{
// stuff
}
#pragma endregion
In other words, manually putting in exactly what Visual Studio will automagically put in for C# code for you.
Then give the Intellisense engine a minute or so to reparse the file. Doing a build will force it to reparse, of course.
As I recall, this works in the most recent VS2010 Express Community, but I don't recall whether it worked in VS2010 Ultimate.
Old question but without accepted answer, so maybe this will help:
Currently in Visual Studio 2019 you can manually write xml documentation that is displayed in the IntelliSense using supported tags from:
https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments
Support for autogenerated xml documentation after typing "///" is coming in Visual Studio 2019 version 16.6 that is currently in the PreRelease state. Check for details: https://learn.microsoft.com/en-us/visualstudio/releases/2019/release-notes-preview