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
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"
Is it possible to embed code to Trac wiki page straight from source code? I mean code blocks, not links pointing to the source. Like
MyCode.java contents
Look at IncludeMacro which is also able to embed from source repository (keyword source:).
Furthermore you can copy source code to wiki and format it with syntax-highlighting, for example:
{{{
#!python
hello = lambda: "world"
}}}
Read more about it here.
You're using 'code blocks' in a way that makes me think of partial citation.
As falkb pointed out, IncludeMacro is the current best way of embedding Trac (and even external) content into a Trac resource, that is rendered with support for Trac's WikiFormatting. But sadly, there is NO such partial citation capability yet.
You may want to at least request it as enhancement for the aforementioned plugin, and could even push it closer to reality by providing valid use case example - or better: some real code to make it happen. Be prepared to test code, if a patch is proposed or - ideally - if the trunk (development) branch receives changes to make partial citation happen.
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...
I'm setting up a documentation about some sort of Library which consists of a C/C++ part and a VHDL part, plus some instructive doxygen-only pages. They have to be put into one self-contained group. Everything works so far, nice and fluffy...
But what if I want to optimize the output in the vhdl-subdirectory by using OPTIMIZE_OUTPUT_VHDL = YES and optimize the output of the c-subdirectory by using OPTIMIZE_OUTPUT_C = YES at the same time?
As far as I understand, using doxygen-tags is not optimal in my case, since it introduces new doxyfile.conf-files in each subdirectory, with independent runs of doxygen in each subdirectory. So, doing this I can't put both parts (c+vhdl) in different subgroups of the same group anymore, and links between the two parts are not possible. Also, the whole module should be "selfcontained", to be includable into bigger documentations, without the special build-structure involved in this solution...
What would you do?
I had the same problem - eventually what we did is:
Create a different directory for C code and VHDL code (+ respective doxygen comment files - as we didn't want to spam the code with doxygen tags everywhere).
Run Doxygen for each of these directories (each with it's own oprimization tag - OPTIMIZE_OUTPUT_VHDL or OPTIMIZE_OUTPUT_C )
Combine (manually!!!- though you can create a script for it) the output of these two directories such that the main page would reference the two directories.
Eventually I decided to shorten the time it takes to generate the documentation, and I just ignore the optimization tags...