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 :)
Related
İn this official tutorial I got the error in title. What should be the reason?
Ptr<Tracker> tracker = Tracker::create( "KCF" );
Here the part of tracking.hpp:
#endcode
of course, you can also add any additional methods of your choice. It should be pointed out,
however, that it is not expected to have a constructor declared, as creation should be done via
the corresponding createTracker() method.
In src/tracker.cpp file add BOILERPLATE_CODE(name,classname) line to the body of
Tracker::create() method you will find there, like :
#code
Ptr<Tracker> Tracker::create( const String& trackerType )
{
BOILERPLATE_CODE("BOOSTING",TrackerBoosting);
BOILERPLATE_CODE("MIL",TrackerMIL);
return Ptr<Tracker>();
}
#endcode
- Finally, you should implement the function with signature :
#code
Ptr<classname> classname::createTracker(const classname::Params ¶meters){
...
}
#endcode
I am using 3.2.0 release.
The code you pasted from tracking.hpp isn't actual code, it's just sample code that's part of the documentation. The only relevant code in the tracking header file is:
#include <opencv2/tracking/tracker.hpp>
#include <opencv2/tracking/tldDataset.hpp>
Thus, to see what you're actually importing you need to look at the tracking/tracker.hpp file (here).
If you do that, you'll see that there's no static create method in the Tracker class declaration. The method was actually removed in this commit. So, basically, you're right: the tutorial wasn't updated after the method was removed. You should report your issue to the opencv team.
That being said, to make the tutorial work you'll probably need to replace the line that's not compiling with:
Ptr<TrackerKCF> tracker = TrackerKCF::create();
That should do the trick.
I've just opened a Qt server example source code. Here is one of the files: http://code.qt.io/cgit/qt/qtbase.git/tree/examples/network/fortuneserver/server.cpp
It has comments like //! [0]. Here's an example:
//! [3]
connect(tcpServer, &QTcpServer::newConnection, this, &Server::sendFortune);
//! [3]
I've never seen them before. What do they mean?
It is used in Qt for generating the web documentation from the source code. usually, wherever you find the //! [NUMBER], you will be able to see that piece of code in the web documentation.
Also, it is found at the end of the code, so the documentation generator tool can know which portion of the code goes where.
Of course, the //! tags are found in the source code, but not in the generated documentation. Otherwise, the documentation would become unreadable.
Why they have used this?
It begins with // (meaning it is a comment, so the compiler will ignore it), and they have added a "!" for the generator tool, so it can separate the code comments from the documentation info.
//![1] This line will be generated into the documentation explaining the following function
void somethingDifficult()
{
//This would be a normal comment, so not exported to documentation
}
//![1] Here we mark the end of the export to the documentation
I couldn't see //! anywhere in that link, but // is the declaration that the rest of the line is a comment.
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.
I ran into a problem with the Eclipse formatter. It won't format my code correctly when declaring methods within a class declaration. It puts a new line after the method's return type.
I already exported the style xml file and examined the settings in it, but none of the settings have any apparent connection to this problem, and the settings editor in Eclipse didn't show the same problem happening in it's sample code for method declarations.
Here is an example bit of code for what I want to have happen:
class MyClass
{
public:
MyClass();
void myMethod();
};
However, this is what I get:
class MyClass
{
public:
MyClass();
void
myMethod();
};
Again, in the styles editor, the code doesn't have this problem and looks just how I want it to, but in the actual code, the story is different.
I'm using version 3.8.0. Any help is appreciated.
Edit: I deleted those source files that were formatted incorrectly (after formatting the code several times to no avail) and replaced them with "identical" files with the same methods, same structure, etc. I formatted the code this time and it worked. This is probably a bug, but I'm leaving it up just in case anyone else encounters a similar problem or has a solution to avoiding this problem in the first place.
I hand edited two files under the main eclipse projects directory
.metadata\.plugins\org.eclipse.core.runtime\.settings
The two files:
file 1: org.eclipse.cdt.core.prefs, change this line from "insert" to "do not insert"
org.eclipse.cdt.core.formatter.insert_new_line_before_identifier_in_function_declaration=do not insert
file 2: org.eclipse.cdt.ui.prefs,
scan this file for "insert_new_line_before_identifier_in_function_declaration" and make a similar change from insert to do not insert next to it, should be obvious
Note I seen this problem on indigo and juno, the fix described above was in juno.
If you have a custom formatter config, export it first (settings>C/C++ General>Formatter>Edit>Export). Then change the following line to "do not insert". Save the XML.
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_identifier_in_function_declaration" value="do not insert"/>
Delete the current config and import the one you changed.
There's a specific preference in the formatter options starting from cdt 9.8 included in Eclipse 2019-06.
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.