What means this special comments in qt examples folder?
I know about "//:" this is a comment than would be taken to a translation program if the next line contains tr("").
The code between //[] seems to be taken to the generated html documentation.
Is there a document with full description of special comments?
Qt uses Doxygen Special Commands in it's code comments. [Okay, to be correct, Doxygen extends Qt's comment special commands.] The special commands are used to control the generation of the documentation when it is run on the code. The Trolls who maintain Qt have their own tool they use to generate documents from the code. Doxygen was written to give us mere mortals a tool we could use.
One of the things you can do with Doxygen (and I assume Qt's tool) is include example code in the documentation. Often, only part of the code is needed, so there are some special commands that can be used to control what portion of the file is displayed (e.g. \line). They rely on finding markers in the code. IMHO, the // [xx] are simply those markers.
This is the document for translation comments, no mention of //[num] though....
Related
I'm working on a C++ project and really fell in love with the Sphinx documentation build system. I managed to setup Doxygen and Breathe to produce and provide the C++ descriptions to Sphinx.
I can't figure out how Google's Ceres Solver documentation was done. Their API reference for example contains class names followed by lots of text, sometimes even with code block examples as shown in the previous link. Is there a way to write Doxygen documentation inside the source files and achieve this?
Another example is this class documentation, which has around two pages of text. I somehow doubt that all this text is located in the source files as Doxygen comments. I have the feeling that all the extra text has been written in the restructured text sources for the documentation and nothing in the c++ source files. But then what is the point of using doxygen and breathe...
Or asked differently, where should I put high-level information about the code? I mean I can document class1 and class2 in their sources, but somewhere I need to explain how both of them interact and are used together. This is what the documentation of the Ceres Solver does so nicely in my opinion.
Alternatively you could point me to a C++ project with the Sphinx + Doxygen + Breathe pipeline and open source documentation. Then I can see for myself how to do these things. Unfortunately I don't know about any project.
I missed the github link for the Ceres Solver. There the sources of the documentation can be found. I'm a bit disappointed, because the complete documentation is written in the Restructured Text source files and NOT inside the c++ code. Basically they reference the class name with .. class:: className and then add ReST markdown for informative text, example code blocks etc. One example is given in "Modeling Non-linear Least Squares"
I have a very simple example Main.cpp file for my library, and I have a tutorial page for it. The page looks something like this:
/**
* #page simpleexample Simple Example
*
* This example shows basic use. It is in \ref simple_example/Main.cpp.
*
* And this is the description of the example.
*/
Now what this does is it replaces the simple_example/Main.cpp reference by a link to that file documentation. I would like it to go directly to the annotated source code.
Is there a way to do it without entirely disabling the per-file documentation? I'd like to have it, but i don't like that people need to click the Main.cpp link and then also the Go to the source code of this file. link once inside. I don't care too much about how the links in the Files section behave, although I'd rather have them go to file documentation, as they do by default.
I don't want to include the source code inside the tutorial page using \example either, as it is already there in small parts which are explained individually.
I found in my old code that I once used main.c_source to reference the annotated source code (not the documentation!), but testing in now it doesn't work...
The best solution I have for you us a hack. Use HTML to reference the actual .html file of the annotated source.
<A HREF=main_8c_source.html><B> main.c annotated source </B></A>
From my observations Doxygen follows a standard renaming scheme. The "." is change to "_8" consistently, and "_source" is appended to reference the source code. Capitals are consistently changed to lower-case and preceded with an underscore. MyFile.c becomes _my_file_8c
You must also set CREATE_SUBDIRS = NO. If CREATE_SUBDIRS = YES then you can't really be sure which sub-directory the file will be in.
Of course as a hack, you can never be sure if it'll work in the next release. You'll always have to be double checking if it still works. Maybe suggest it to them as a Feature request...
Instead of redirecting your reader anywhere you could take a different approach and quote the example code in your tutorial automatically using \include or \snippet.
I agree that the two-step effect of \ref is a bit of a faff, but even having a single step to go look at the code separately from the tutorial text breaks the concentration of the reader.
Depending on the volume of code in your 'example' you could either have it inserted into the doxygen output in its entirety with \include or you could quote the key parts in your tutorial page using \snippet. The latter has the advantage that you can do it in parts interspersed by your tutorial text.
Both these have the mixed blessing that the included sample is treated as code. This means that the doxygen comments in the target file will be shown as code rather than as doxygen. This might seem undesirable but it will help make it clear which is tutorial text and which is the example file. (That said, I've only ever used snippet for just quoting real code samples in a tutorial page myself.)
Relevant Doxygen manual section here.
I note you're not wanting to use \example. My approach is slightly different (especially with \snippet), and doesn't create the 'Examples' page. This may still not be what you want, but I offer it here in case it's useful for others anyway.
I tried some of the possibilities and what worked for me was to create separate pages for the example code.
/**
* #page simpleexample Simple Example
*
* This example shows basic use. It is in \ref simple_example_main.
*
* And this is the description of the example.
*
* #page simple_example_main Main.cpp
*
* \include simple_example/Main.cpp
*/
That would give you the output
This example shows basic use. It is in Main.cpp
Whereas I found the direct insertion of code from the \include command rather useful, as it allows you to insert more than one source per page, and have some floating text between the code files.
In order to get (any) example to work, you need to set the example path, in the example above it would probably be something like
EXAMPLE_PATH = simple_example
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = YES
I work on unix.
I have my complete source code in unix in the form of building blocks and modules.
Like headers,sources files,make files etc.
I can copy all the files with the same directory structure to windows.
I need some tool which will convert all the source to html tags with all the links to functions,variables,classes,headers.There should be some tool to do this easily.
by this way it would be easy for debugging the code in a fast way.
Is anybody aware of such tool?
The term you're probably looking for is "documentation generator". You're specifically interested in ones that output HTML files.
Doxygen is popular, but if you want a master comparison list of documentation generators Wikipedia has a summary:
http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
Looking at the output generated by the different programs (on projects that use them) will probably inform your choice of which meets your needs.
You can use doxygen to generate your documentation. In its basic form it will generate what you need but to add comments that appear in the final html you will need to use special style comments.
I am trying to develop a tool that inserts comments in C/C++ source files in pre-defined formats.
The comments could be:
file headers <-> file names required
class comments <-> class name required
function comments <-> function name required
Following points are required to be taken mind:
If the comments are already there in right format then leave them intact.
If the comments are broken them fix them and insert them.
Some desirable but non important features:
Check and fix the indentation.
Check if any breaks are missing in their respective cases.
Please suggest open-source / free libraries / logic to aid in this.
I guess you 've got two choices:
Generate the whole c/c++ code and headers from a template or scripting language and use this one to insert the preformated comments. This is of course not an option if you still got a lot of code.
Or you need a tool to parse the code into sth. you can further use. You could try doxygen to generate html, xml or some other format. Problem would still be, how to get the generated documentation back into your sources...
when i read through source files of opensource projects i often come across some weird phrases in the comments
/*
#brief ......
#usage.....
#remarks....
#par....
*/
questions
1.What are they?(were not mentioned when i was learning c++)
2.Do they have any documentation(where)
They are just comments and as such have no special meaning in C++. They are probably to allow a documentation generator (For example Doxygen) to extract the data from the comments.
Those are for some flavour of automatic documentation generator. Another program runs through the code looking for comments of like you see there. The #... keywords identify how the documentation should be laid out, and that program generates pretty HTML or printed documentation directly from the source code. It's a way to keep the docs up-to-date with the code more easily.