I am trying to include a .ini file in the doxygen documentation of a C++ class, using \include. This works fine, but for some reason, doxygen treats the contents of the file as C code, which leads to strange formatting. I know \include surrounds the included file with a \code block, and that you can pass specific language information to the code block by using e.g. \code{.unparsed}. Is there a way to do the same with \include? \include{.unparsed} does not work...
Seems the answer to the question is "no": you cannot indicate a language when using \include, since doxygen tries to determine the language based on the extension. If it fails to do so, it reverts to C. If you do not want C formatting for unsupported file extensions, you can use \verbinclude instead of \include.
Related
I'm trying to make notes files with either file type extension .txt or no extension (like notes.txt vs notes), but VS Code is insisting on syntax coloring, and I'm not seeing an option to disable it or even modify the settings.
The syntax coloring makes no sense to me anyway when I'm just writing English sentences, so it's just gumming up my usage. I can't even tell what language it's trying to check against. JSON coloring pasted into the file looks nice, but otherwise it's completely random to me.
In my configuration file in the INPUT tag I added one directory. Inside that iostream is there without any extension. After running the configuration file I'm not getting information related to iostream. I want to know how to add the files without extension in doxygen configuration file.
I created a small test example (contents is not that relevant for this test), file stdio:
/// the fie
void fie(void);
From the documentation (https://www.doxygen.nl/manual/config.html#cfg_extension_mapping):
EXTENSION_MAPPING
Doxygen selects the parser to use depending on the extension of the files it parses.
With this tag you can assign which parser to use for a given extension. Doxygen has a built-in mapping, but you can override or extend it using this tag. The format is ext=language, where ext is a file extension, and language is one of the parsers supported by doxygen: IDL, Java, JavaScript, Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: Fortran. In the later case the parser tries to guess whether the code is fixed or free formatted code, this is the default for Fortran type files).
For instance to make doxygen treat .inc files as Fortran files (default is PHP), and .f files as C (default is Fortran), use: inc=Fortran f=C.
Note: For files without extension you can use no_extension as a placeholder.
Note that for custom extensions you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
Here we see that the possibility for no_extension and with the following setting we get the requested information:
EXTRACT_ALL=YES
INPUT = stdio
EXTENSION_MAPPING = no_extension=C++
and I do see the stdio information.
Edit
In case doesn't want to add all files one by one one hast to add * to FILE_PATTERNS.
I am trying to separate out internal and external documentation using the doxygen constructs of cond; but i just cant seem to get get it working. I would essentially like to exclude some files completely and not conditionally. Regardless of where i add the tag (before include, before header guards etc) , the files and source both show up.
What i have tried in vain is to take the test file from doxegen repo for
conditional test and add it to the project.
Steps to reproduce [Linux]
create a new directory.
copy paste the above file (had to rename it to .h as .c was passed over?).
generate dummy config via doxygen -g.
update Doxyfile ENABLED_SECTION = COND_ENABLED.
Run doxygen.
check html/index.html
This however is still visible in the html documentation it generates for the project. I have set the ENABLED_SECTION variable with other values , but cond_enabled function still shows up. Running the testing directory of the project (doxygen) it passes. So i am lost.
Any suggestions?
Tried with latest version 1.8.14.
Thanks!
Regarding the \cond problems (not an answer directly to the real problem you face, I think, but to long for a comment).
The mentioned file is used in the, limited, testing doxygen can do / does and the first lines contain some instructions on what to do. Furthermore there is a default Doxyfile with the tests in use. It is hard to run a separate test outside the doxygen build tree.
Regarding the remark "Running the testing directory of the project (doxygen) it passes." This is correct, here, at the moment, only testing is done against the XML output and the generated output is compared to a once created version of the XML output. No tests are done, at the moment, in respect to HTML or PDF / LaTeX. Recently the test framework has been slightly extended so in the future this should be possible (compare the xhtml and tex output, but some work has still to be done here).
The version of the parser sees the \cond in the first line (normal C comment) as a doxygen command and skips everything till the first \endcond (your friend in these cases is always doxygen -d preprocessor). I think that removing / modifying the first line will result in an already better result. There is however another hiccup for e.g. HTML output. As the function cond_enabled is not documented and EXPAND_ALL is not set to YES the function will not appear in the documentation. So best is also to add a line of documentation with the function cond_enabled.
Regarding the seen HTML problems I modified the the relevant test in doxygen slightly and pushed a proposed patch to github (pull request 714, https://github.com/doxygen/doxygen/pull/714).
Note: the problem of skipping the \cond in normal C comment is quite a bit harder to implement (seen the logical complexity of the doxygen code in pre.l and commentcnv.l.
EDIT: 2018/06/10: The push request has been integrated in the master version on github.
I'm updating some Doxygen documentation, and when Doxygen generates the code blocks for the documentation, it no longer puts the code in a block when it's surrounded by the \code and \endcode tags.
Original:
New:
The documentation was originally generated with 1.6.1, and the new documentation is using 1.8.1.2. Since the versions are different, do I now have to use the markdown syntax to generate the proper code blocks, or can I continue to use the \code tags?
No, \code..\endcode still works as always.
What is like the problem is that you use a custom page header or stylesheet (i.e. HTML_STYLESHEET or HTML_HEADER is not empty in the config file) and the newer version of doxygen started using different CSS tags to style the code block, and these are missing from your stylesheet.
Doxygen recently introduced a HTML_EXTRA_STYLESHEET option which you can use to overrule parts of the original stylesheet. I recommend to use that option instead of HTML_STYLESHEET.
I need to refer to Doxygen documentation pages. The file names however are not stable as they change after every generation. My idea is to create a symlink to each HTML file created by Doxygen , having a stable and human friendly name. Have anyone tried this?
Actually, it might be very easy just to parse the annotated.html file Doxygen produces. Any documented class shows up there as a line like:
`<tr><td class="indexkey"><a class="el" href="dd/de6/a00548.html">
ImportantClass</a></td>`
The hard problem for me is that I would like to have my file names (i.e. the symlinks) be visible on my server like:
http://www.package.com/com.package.my.ImportantClass.html
[Yes, the code is in java]. So the question actually reads: "how to connect a HTML page by Doxygen with the right java class name and its package name.
You seem to have SHORT_NAMES enabled, which will indeed produce volatile names. When you set SHORT_NAMES to NO in the configuration file (the default), you will get longer names, but these are stable over multiple runs (i.e. they are based on the name, and for functions also on (a hash of) the parameters.