I'm working on a C++ project in the field of automatics I'd like to start documenting. I'm rather decided for Doxygen. But, apart of documenting particular fields of data and drawing class-hierarchy UML-diagrams, I'd like to document several methods' functionalities with block diagrams like this one:
What are the solutions?
I'm familiar with LaTeX. I've read Doxygen has some support for LaTeX, I don't know how far this goes, though. Is it possible to use any LaTeX package within Doxygen? Which particular packages would you recommend and could you provide some simple examples as well?
I'm also open to recommendations of something different than Doxygen.
If it's only about getting the control-systems structure, variables etc. documented you can generate the diagram elsewhere (e.g. Dia, XFig or Inkscape if you want to use open source tools) and embed them into your Doxygen documentation via the image keyword from within your code:
/*!
.. Doxygen doc here..
\image html Data_Model.png "Figure 1: UML Diagram of the Data Source and Data Model Relationships"
*/
To do this you'll need to tell Doxygen in the Doxyfile file where to find the images, and place the images relative to your doxygen path (DOCROOT/images in this case):
# The IMAGE_PATH tag can be used to specify one or more files or
# directories that contain image that are included in the documentation (see
# the \image command).
IMAGE_PATH = images
Using latex extensions or other language driven graphical markups for generating graphs from within Doxygen doc does imho not justify the overhead of learning the language, getting the tool-chain configured and aligned. On the other hand if you have some tool already which is generating the graph automatically (from your code or a config file), it should be a breeze to run the tool from within a Makefile, let it generate the image and embed the image in your doxygen doc via the image keyword.
Related
I need to do some research in MDA/MDD to find Open-Source-Tools which will help me to develop code-generators and transformators.
But there are only a few tools which are actually supported. Do I search in the wrong direction?
Do You know open source tools for MDA/MDD?
Greetings Dominic
I found andromda, Eclipse Modelling Framework and a few tools like plantuml, which help to create diagrams .
My plan is to read diagrams with plantuml and convert them with emf to code and the reverse way.
Telosys could be a solution to your need (https://doc.telosys.org/)
Telosys has its own DSL to define the models (based on text files with a simple grammar), see https://doc.telosys.org/dsl-model
A Telosys model can be used to generate any kind of target language (including PlantUML) but Telosys cannot parse PlantUML files, so the input model must be a Telosys model (or a database schema if you create the model from a relational DB).
I batch create the documents from the code by using doxygen. However, I lost code and I didn't lose the document. I want to convert the code back from the documents. Is there any option in doxygen to do this? Thank you very much.
By the way, the documents are all html files
Doxygen is a documentation generator; it's job is to go from code to documentation. As such, it has no functionality for reversing this process. Especially since the generated HTML can change from version to version.
Documentation conversion is also an inherently lossy process. Unless you outputted all of your source code into the documentation, you're not going to be able to reconstruct everything. The best you might do is rebuild most aspects of some headers, but even then, anything that goes undocumented (like header include files and such) won't be in the HTML.
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....