I've been following a C++ tutorial, and would like to comment some of the parameters and methods for convenience so that their associated comments are displayed when I hover over them (uses Intellisense I believe). I know how to do this in C#, but haven't been able to figure it out in C++.
In Visual C# 2010 express, I could do the following:
Type "///" and the summary and param tag were automatically created. Filling in the comments I could create:
/// <summary>
/// Constructor.
/// </summary>
/// <param name="value_Initial">Initial value.</param>
public DataObject_Float(float value_Initial){
...
}
such that hovering over them displayed their parameter and method info. The closest I've been able to get is:
// Constructor.
// value_Initial = Initial value
which is not ideal.
How can I do/emulate this behavior in VS Ultimate 2010 in C++, even if I have to manually type out the tags, variable names, etc. I have been unable to figure out/find the syntax for this.
The compiler does not use CLR, which apparently isn't supported by Intellisense. I've also installed a trial version of Visual Assist X, if that could be used to help with this. Additionaly, should the comments for the methods and parameters be placed in the header file or the .cpp file?
The syntax for VC++ doc comments is reasonably documented in two places. One is the recommended tags and the other is the delimiters.
The doc comments will not show up in hover text, but they will show up in when the auto-complete list is up (i.e. that will show the symbol declaration, any doc comments, and the symbol the file is declared in.
I believe you want to put the doc comments in the header as it seems to be picked for the current translation unit only (i.e. meaning if it's the .cpp you'll only see it when you are in that single .cpp file).
Related
How do I change the highlight color of the Doxygen tokens like #param or #return so it matches the same visual as JSdoc comments?
What I currently have in my .cpp/.hpp files:
What I would like to see (this is inside a .js file):
For example, is there a way to tell VSCode, all #params strings should be blue?
I managed to get JSDoc like comment blocks highlighting using the Better C++ syntax package. For more customization checkout this issue thread.
EDIT: After we determined that your jsdoc comment syntax was not being separately parsed, you found the Better C++ Syntax package which does so. And gives you more control over the contents of a jsdoc comments's internals. Now this textmate scope will give you the blue colored #'s parameters you desired.
Try this in your settings.json
"editor.tokenColorCustomizations": {
"textMateRules": [
{
"scope": "storage.type.class.doxygen.cpp",
"settings": {
"foreground": "#00f"
}
}
]
}
You can get the scope by using the Developer: Inspect TM Scopes command from the command palette. This allows you to click on a word in your editor, like #param and see its textmate scope. Which then goes into the tokenColorCustomizations rule.
There are typically 3 or 4 scopes listed which you can use in a space-separated list if you want more distinction. Such as if you wanted this rule to apply only to js docs:
"scope": " source.cpp storage.type.class.doxygen.cpp
Besides the foreground color you can also set its fontStyle here as well. Options are: italic, bold and underline - which can be used in combination with each other too.
As you noticed, with that Beter C++ Syntax package, you need to use #brief instead of #desc in your cpp jsdoc-like comments.
I'm trying to get doxygen 1.8.7 to include detailed descriptions in the HTML output. For example, given the following file:
/** \file iniparse.h */
namespace ini {
/** \brief A brief description.
*
* A longer description.
*/
inline void parse() {}
}
My HTML for iniparse.h contains an entry for ini::parse, with text "A brief description. More..." The "More..." part is a broken link to a non-existent anchor in the same page. And the text "A longer description" appears nowhere in the generated HTML.
If I get rid of the namespace and just define a function parse (i.e., ::parse) outside of any namespace, things work fine. Can someone tell me how to get the same behavior inside a namespace? Thanks.
Turns out this problem is caused by a combination of three things. First, a plain old bug in doxygen:
https://bugzilla.gnome.org/show_bug.cgi?id=745481
Second, even with the bug fix, you need to generate the namespaces page or you still get broken links. Hence, you need to have SHOW_NAMESPACES = YES in your Doxyfile.
Third, unless you have EXTRACT_ALL = YES, you have to make sure the namespace itself is documented by attaching a Doxygen comment to it. So you need:
//! The ini namespace
namespace ini {
...
}
On one hand maybe it makes sense to require namespaces to be documented if you want documentation for their contents. However, it's weird that doxygen shows the first part of the documentation even without the namespace documentation. So I would argue this is still kind of a bug, but at least I know how to work around it now.
I've decided to document the code for my project. I found this tool Doxygen online and downloaded it.
But when I try to actually create an HTML file, it just displays the project contents and none of the special comments above the function.
I tried all types of comments - /*! ... */ , /** ... */ , ///,//!
It displays only the name of a function and its definition in the .h file, like this:
How can I fix this? How can I enable Doxygen to display the special comments too?
If I understand correctly, you are just using these special markers on code comments placed in the usual way inside functions? Check that your front-end isn't using
HIDE_IN_BODY_DOCS
If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any documentation blocks found inside the body of a function. If set to NO these blocks will be appended to the function's detailed documentation block.
The default value is: NO.
You also probably want to enable
EXTRACT_ALL
If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in documentation are documented, even if no documentation was available. Private class members and static file members will be hidden unless the EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
Note
This will also disable the warnings about undocumented members that are normally produced when WARNINGS is set to YES.
The default value is: NO.
I haven't specifically tested whether comments in a function body count as "documentation was available", but if you don't have parameter documentation in the doxygen format, I'd definitely turn on EXTRACT_ALL.
Doxygen by itself is a very efficient tool, but you have to learn how to use it. The key is the configuration file. The command:
doxygen -g
Will generate for you a default one in the current folder. You then need to edit it, either directly using any text editor, either through a GUI program that is name doxywizard. The default options values are usually a good start, but maybe you switched something ?
This commenting style should work:
/// define foo
#define foo 42
/// a truely efficient function
void foobar();
struct A {
int b; ///< this is something
};
I am trying to migrate a VS 2005 project to VS 2012. But it reports the following error.
The "HasTrailingSlash" function only accepts a scalar value, but its
argument "$(IntDir)" evaluates to
"C:\Users\Mahesh\HelloWorld_obj\DebugW7-Win32;\" which is not a
scalar value. C:\Program Files
(x86)\MSBuild\Microsoft.Cpp\v4.0\V110\Microsoft.Cpp.targets
I understand its a string literal and not a scalar value. But how to resolve the issue. Can anyone please share your ideas. Googling didn't help much.
Failed attempt : Though changing the delimeter to / from ; for the macro serving as intermediate directory in the property sheet did not work.
Success: I opened the property sheet in Notepad and removed the following lines for the user macro "ObjOut" which serves as an intermediate directory for my project.
InheritsFromParent="true"
Delimiter=";"
The same can be achieved via IDE as well when "Macro inherits from parent property sheets" is unchecked for the macro.
Hope this is useful to someone in future. I posted the same on MSDN forum as well.
I'm trying to create a new C++ project in VS 10, and can't even get an empty project to load from the template. I get an error...
The "exists" function only accepts a scalar value but its argument "$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" evaluates to "{~}" which is not a scalar value.
The {~} value is what I have stored in the LOCALAPPDATA variable in the computer Environment Variables, concatenated with "\Microsoft\MSBuild\v4.0\Microsoft.Cpp.Win32.user.props" at the end.
I'm reluctant to go changing any template files without understanding what's going on.
Well, it looks like Windows XP doesn't provide any default value for this variable and "~" is definitely not a valid directory on your PC. Try to set it as described here, and maybe you'll get lucky. VS2010 had some bug related to this. Perhaps you also need to upgrade it to SP1.
The links provided by #Mihai gave the information I needed to find a solution. The problem was that LocalAppData didn't have the value it was looking for (just what the error message says). I couldn't change that data because other apps had modified it for their own purposes (the value wasn't "~", that was a placeholder for this post).
Instead, I opened the .vcxproj file in Notepad, and modified the ImportGroup nodes causing the error. Instead of the attribute:
Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')"
... it now reads
Condition="exists('$(UserProfile)\Local Settings\Application Data\Microsoft.Cpp.$(Platform).user.props')"
The project now loads.