Every time I create a .cpp/.h file on CLion, I get an automatic file header like this:
//
// Created by me on 09/11/18.
//
This is neat, but I'd rather like something Doxygen-compliant like this:
/*!
* #author me
* #date 03/12/18.
*/
I could easily edit this and add more Doxygen-fields thanks to the nice CLion integration.
This seems a trivial task, but I still did not manage to achieve it. May someone help me out?
Regards,
Edit:
As suggested, I went to "File and Code Templates", then clicked on the "Includes" Tab (Files was selected by default) and I found the pattern I was looking for. I modified it as in the following:
#if ($HEADER_COMMENTS)
/*!
* #author $USER_NAME
* #date ${DATE}
#if ($ORGANIZATION_NAME && $ORGANIZATION_NAME != "")
* Copyright (c) $YEAR ${ORGANIZATION_NAME}#if (!$ORGANIZATION_NAME.endsWith(".")).#end All rights reserved.
#end
*/
#end
Go to File->Settings...->Editor->File and Code Templates->Includes.
There you will find an include called C File Header which is included by all other C/C++ related file types and can be adjusted for your needs.
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
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 :)
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.
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.
Consider I have 2 header files.
// HEADER 1
/**
* Doc for Foo here?
*/
namespace Foo {
class This {...};
}
&&
// HEADER 2
/**
* Doc for Foo here?
*/
namespace Foo {
class That {...};
}
How should I handle this when documenting with Doxygen?
Maybe neither.
For example, imagine you have "<root>/utility/header1.hpp" which has its contents in namespace utility and "<root>/utility/header2.hpp" which does also.
You could add a file: "<root>/utility.hpp" which documents the utility namespace. You could put this at the top #error Documentation only. to make sure it's not accidentally included.
But I would recommend at least making some out-of-the-way file to keep it in a sane place (and not mixed in randomly with some class.)
I have placed documentation for namespaces that span multiple files into another file. My Doxygen builds use a separate file for the #mainpage tag. This forms the root of the built Doxygen, and is also a central location for such namespaces.
So I'll have project_name_mainpage.h, and in that file:
/**
#mainpage title
...whatever you want to tell the user about your application...
*/
/**
* #namespace your_namespace
* #brief An awesome description
* #details More sweet details
*/
Keeps it all in one place, and is relatively easy to find if you need to update it.
Find the best place for the documentation, whether it is in one of those files or another entirely. Use a comment block with Doxygen's namespace tag:
/**
* #namespace Foo
* Documentation for Foo here. More docs for Foo here,
* and down here.
*/
Docs here: http://www.doxygen.nl/manual/commands.html#cmdnamespace