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.
Related
It seems trivial, but I've searched far and wide.
I'm using this resource to make v8 run with ES Modules and I'm trying to implement my own search/load algorithm. Thus far, I've managed to make a simple system which loads a file from a known location, however I'd like to implement external modules. This means that the known location is actually unknown throughout the application. Take the following directory tree as an example:
~/
- index.js
import 'module1_index'; // This is successfully resolved to /libs/module1/module1_index.js
/libs/module1/
- module1_index.js
export * from './lib.js' // This import fails because it is looking for ./lib.js in ~/source
- lib.js
export /* literally anything */
The above example begins by executing the index.js file from ~. When module1_index.js is executed, lib.js is looked for from ~ and consequently fails. In order to address this, the files must be looked for relative to the file being executed at the moment, however I have not found a means to do this.
First Attempt
I'm given the opportunity to look for the file in the callResolve method (main.cpp:280):
v8::MaybeLocal<v8::Module> callResolve(v8::Local<v8::Context> context, v8::Local<v8::String> specifier, v8::Local<v8::Module> referrer)
or in loadModule (main.cpp:197)
v8::MaybeLocal<v8::Module> loadModule(char code[], char name[], v8::Local<v8::Context> cx)
however, as mentioned, I have found no function by which to extract the ScriptOrigin from the module. I should mention, when files are successfully resolved, the ScriptOrigin is initiated with the exact path to the file, and is reliable.
Second Attempt
I set up a stack, which keeps track of the current file being executed. Every import which is made is pushed onto the stack. Once the file has finished executing, it is popped. This also did not work, as there was no way to reliably determine once the file had finished executing.
It seems that the loadModule function does just that: loads. It does not execute, so I cannot pop after the module has loaded, as the imports are not fully resolved. The checkModule/execModule functions are only invoked on dynamic imports, making them useless to determining the completion of a static import.
I'm at a loss. I'm not familiar with v8 enough to know where to look, although I have dug through some NodeJS source code looking for an implementation, to no avail.
Any pointers are greatly appreciated.
Thanks.
Jake.
I don't know much about module resolution, but looking at V8's sources, I can see an example mapping a v8::Module to a std::string absolute_path, which sounds like what you're looking for. I'm not copying the whole code here, because the way it uses custom metadata is a bit involved; the short story is that it keeps a std::unordered_map to keep data about each module's source on the side. (I wonder if it would be possible to use Module::ScriptId() as that map's key, for simplification.)
Code search finds a bunch more example uses of InstantiateModule, mostly in tests. Tests often serve as useful examples/documentation :-)
I'm trying to use https://github.com/venantius/yagni
When I run it, I get the following error:
=================== WARNING: Parents ======================
== Could not find any references to the following ==
===========================================================
my-proj.my-ns/my-proj.my-ns.proxy$java.lang.Object$Callable$7da976d4
From what I found online, nothing can explain the meaning of this error
Update
Thanks for the comments asking me to give more context.
I was able to understand that the error is coming from a macro I'm using.
In my code, I'm using the time! macro, from the metrics lib.
As you can see herethis macro is using proxy
But this is not my code, is there a way to tell yagni not to look at it? (I guess not since it is a macro and compiled before yagni reads it)
İ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 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.