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.
Related
I have a set of .groovy files (Java). All of these files have the same comment format.
I developped a tool with wich I'm able to read those files and applying a REGEX to get all the comments in a list. (Finally i just have to copy paste these comments to .html file)
I would like to know if it's a correct practice in order to generate a HTML page with the comment (a kind of documentation). If not, what would you recommend ?
I read about Doxygen and Javadoc but i'm not sure about using them (if they can be really useful in my case since the comments are already written)
If you can suggest a library in order to generate easily a HTML Webpage or any other advice.
Any help is appreciated.
There exists Groovydoc which is roughly the equivalent of Javadoc, just for Groovy.
As your setup is not that (you already have comments, probably not in Groovydoc format, and you have half the tooling), there are still multiple ways open to you. As you already extract the documentation from groovy, if I were you, I would do a minimal post-formatting, if necessary, and output the documentation as markdown (e.g., github markdown) or asciidoc (e.g., asciidoctor). Then you can use any preferred tool to convert the post-formatted documentation into HTML.
To answer the question "How to parse the java comments" – you shouldn't. If possible, especially in a new project, stick with the standard tooling. In the case of Groovy that's Groovydoc. The normal (non Java/Groovy-Doc style) comments themselves you should never need to extract from the source code. They should be so much context-specific, that without the corresponding code they are anyways useless.
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 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.
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....
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...