I have a problem with generating documentation for files with # in their names. I.e. :
Filename ab#cd.h starts with line:
/** #file ab#cd.h some description */
This description is missing in generated Doxygen HTML.
Also all links were wrong but they have been fixed by additional script which exchange # into %23. I'm thinking of another script for renaming file name before and after generation but maybe there is a possibility to deal with the issue in some other way?
Why # char influence Doxygen documentation generation?
Hashes in filenames are a recipe for problems, but in your example you could simply write
/** #file
* some description
*/
No need for the file name, and the description should be put on the next line.
Doxygen uses # for links. I believe you can escape a # with a \, but I'm not positive.
Related
We have a number of makefile templates, that realize certain build actions by setting a few parameter makefile variables, and applying a makefile template via inclusion like
GENERIC_PARAM1-y := paramA
GENERIC_PARAM2-y := paramB
include $(MAKE_TOOLS)/doaction.mk
And files like doaction.mk contain make templates to generate standard rule definitions that are applied when just including the action make step.
Now we want to document these interfaces for the *.mk snippets using Doxygen like
## #file
## #brief doaction.mk is purposed to ...
##
## Some more detailed descriptions about rules applied ...
## #param GENERIC_PARAM1-y Parameter1 description ...
## #param GENERIC_PARAM2-y Parameter2 description ...
Is there a simple way to achieve this using any valid Doxygen syntax/configuration?
"Is there a simple way to achieve this using any valid doxygen syntax/configuration?"
Yes, you can use doxygen's INPUT_FILTER, FILE_PATTERNS and FILTER_SOURCE_FILES configuration settings as stolen from this blog post
Put these settings in your Doxyfile configuration
FILE_PATTERNS = *.mk
INPUT_FILTER = "sed -e 's|##|//!|'"
FILTER_SOURCE_FILES = YES
The INPUT_FILTER actually does the trick, the sed command is used by doxygen to open a pipe filtering the input files along the specified command.
Note:
The above mentioned command isn't embedded into a shell, thus chained command statements like
"grep '##' | sed -e 's|##|//!|'"
won't work.
Put your comments as proposed in the sample ## will expand for comments seen by doxygen
## #file
## #brief doaction.mk is purposed to ...
##
## Some more detailed descriptions about rules applied ...
## #param GENERIC_PARAM1-y Parameter1 description ...
## #param GENERIC_PARAM2-y Parameter2 description ...
Additionally you should put a
## #cond
...
## #endcond
around your makefile rules/templates code, to avoid doxygen parsing these parts.
The above sample should render as follows in the generated documentation HTML
I find myself in a situation where I would like to accurately document a host of custom CMake macros and functions and was wondering how to do it.
The first thing that comes to mind is simply using the built-in syntax and only document scripts, like so:
# -----------------------------
# [FUNCTION_NAME | MACRO_NAME]
# -----------------------------
# ... description ...
# -----------------------------
This is fine. However, I'd like to employ common doc generators, for instance doxygen, to also generate external documentation that can be read by anyone without looking at the implementation (which is a common scenario).
One way would be to write a simple parser that generates a corresponding C/C++ header with the appropriate signatures and documentation directly from the CMake script, which could the be processed by doxygen or comparable tools. One could also maintain such a header by hand - which is obviously tedious and error prone.
Is there any other way to employ a documentation generator with CMake scripts?
Here is the closest I could get. The following was tested with CMake 2.8.10. Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.
CMake 2.8 can extract documentation from your modules, but only documentation at the beginning of the file is considered. All documentation is added as CMake comments, beginning with a single #. Double ## will be ignored (so you can add comments to your documentation). The end of documentation is marked by the first non-comment line (e.g. an empty line)
The first line gives a brief description of the module. It must start with - and end with a period . or a blank line.
# - My first documented CMake module.
# description
or
# - My first documented CMake module
#
# description
In HTML, lines starting with at two or more spaces (after the #) are formatted with monospace font.
Example:
# - My custom macros to do foo
#
# This module provides the macro foo().
# These macros serve to demonstrate the documentation capabilietes of CMake.
#
# FOO( [FILENAME <file>]
# [APPEND]
# [VAR <variable_name>]
# )
#
# The FOO() macro can be used to do foo or bar. If FILENAME is given,
# it even writes baz.
MACRO( FOO )
...
ENDMACRO()
To generate documentation for your custom modules only, call
cmake -DCMAKE_MODULE_PATH:STRING=. --help-custom-modules test.html
Setting CMAKE_MODULE_PATH allows you to define additional directories to search for modules. Otherwise, your modules need to be in the default CMake location. --help-custom-modules limits the documentation generation to custom, non-CMake-standar modules. If you give a filename, the documentation is written to the file, to stdout otherwise. If the filename has a recognized extension, the documentation is formatted accordingly.
The following formats are possible:
.html for HTML documentation
.1 to .9 for man page
.docbook for Docbook
anything else: plain text
I am starting to dokumenting with doxygen and as far as it goes it seems quite easy and helpful !
There is just one file which gives me a headache, my config.ini .
This file has different comments, standards etc. .
I would like to load it as "code", so the page is not interpreted.
How can I achieve this ?
The following didn't work :
; /// #file config.ini
; /// #code
setting1
setting2
setting3
; /// #endcode
Your question is a little unclear but I assume from your question that you do want to see the contents of the .ini file in the documentation.
For what I think you need I'd suggest using #verbatim rather than #code.
If you are not seeing anything at all, then check that .ini is in the list of filename extensions that doxygen will parse? It's a setting in the doxyfile.
You can do what you want as follows:
Define a page that includes the .ini file, for instance test.dox as follows:
/** #page test_ini test.ini
* This is the configuration file:
* #verbinclude test.ini
*/
Then set EXAMPLE_PATH in doxygen's config file to the directory that contains test.ini and don't include .ini files in FILE_PATTERNS (so use the default).
I am trying to use some Doxygen filter for Visual Basic in Windows.
I started with Vsevolod Kukol filter, based on gawk.
There are not so many directions.
So I started using his own commented VB code VB6Module.bas and, by means of his vbfilter.awk, I issued:
gawk -f vbfilter.awk VB6Module.bas
This outputs a C-like code on stdin. Therefore I redirected it to a file with:
gawk -f vbfilter.awk VB6Module.bas>awkout.txt
I created this Doxygen test.cfg file:
PROJECT_NAME = "Test"
OUTPUT_DIRECTORY = test
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = awkout.txt
QUIET = NO
JAVADOC_AUTOBRIEF = NO
SEARCHENGINE = NO
To produce the documentation I issued:
doxygen test.cfg
Doxygen complains as the "name 'VB6Module.bas' supplied as the second argument in the \file statement is not an input file." I removed the comment #file VB6Module.bas from awkout.txt. The warning stopped, but in both cases the documentation produced was just a single page with the project name.
I tried also the alternative filter by Basti Grembowietz in Python vbfilter.py. Again without documentation, again producing errors and without any useful output.
After trials and errors I solved the problem.
I was unable to convert a .bas file in a format such that I can pass it to Doxygen as input.
Anyway, following #doxygen user suggestions, I was able to create a Doxygen config file such that it can interpret the .bas file comments properly.
Given the file VB6Module.bas (by the Doxygen-VB-Filter author, Vsevolod Kukol), commented with Doxygen style adapted for Visual Basic, I wrote the Doxygen config file, test.cfg, as follows:
PROJECT_NAME = "Test"
OUTPUT_DIRECTORY = test
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = readme.md VB6Module.bas
QUIET = YES
JAVADOC_AUTOBRIEF = NO
SEARCHENGINE = NO
FILTER_PATTERNS = "*.bas=vbfilter.bat"
where:
readme.md is any Markdown file that can used as the main documentation page.
vbfilter.bat contains:
#echo off
gawk.exe -f vbfilter.awk "%1%"
vbfilter.awk by the filter author is assumed to be in the same folder as the input files to be documented and obviously gawk should be in the path.
Running:
doxygen test.cfg
everything is smooth, apart two apparently innocuous warnings:
gawk: vbfilter.awk:528: warning: escape sequence `\[' treated as plain `['
gawk: vbfilter.awk:528: warning: escape sequence `\]' treated as plain `]'
Now test\html\index.html contains the proper documentation as extracted by the ".bas" and the Markdown files.
Alright I did some work:
You can download this .zip file. It contains:
MakeDoxy.bas The macro that makes it all happen
makedoxy.cmd A shell script that will be executed by MakeDoxy
configuration Folder that contains doxygen and gawk binaries which are needed to create the doxygen documentation as well as some additional filtering files which were already used by the OP.
source Folder that contains example source code for doxygen
How To Use:
Note: I tested it with Excel 2010
Extract VBADoxy.zip somehwere (referenced as <root> from now on)
Import MakeDoxy.bas into your VBA project. You can also import the files from source or use your own doxygen-documented VBA code files but you'll need at least one documented file in the same VBA project.
Add "Microsoft Visual Basic for Applications Extensibility 5.3" or higher to your VBA Project References (did not test it with lower versions). It's needed for the export-part (VBProject, VBComponent).
Run macro MakeDoxy
What is going to happen:
You will be asked for the <root> folder.
You will be asked if you want to delete <root>\source afterwards It is okay to delete those files. They will not be removed from your VBA Project.
MakeDoxy will export all .bas, cls and .frm files to location:<root>\source\<modulename>\<modulename>(.bas|.cls|.frm)
cmd.exewill be commanded to run makedoxy.cmd and delete <root>\source if you've chosen that way which alltogether will result in your desired documentation.
A logfile MakeDoxy.bas.logwill be re-created each time MakeDoxy is executed.
You can play with configuration\vbdoxy.cfg a little if you want to change doxygens behavior.
There is still some room for improvements but I guess this is something one can work with.
I Have two files with the same name but in two different directories.
graphic_test ---semLib.c
|
|
-- vxWorksApi---semLib.c
I want to build a Html with Doxygen. this is the header of the file semLib.c
/**
* #file semLib.c
*/
And I got this message
Multiple markers at this line
- the name `semLib.c' supplied as the second argument in the \file statement matches the following input files: /home/linuxdev/
Linux_Development_Workspace/graphic_tests/graphic_test/semLib.c /home/linuxdev/Linux_Development_Workspace/graphic_tests/vxWorksApi/semLib.c
- Line breakpoint: semLib.c [line: 2]
How can I avoid this?
From the doxygen documentation for the \file command (emphasis mine):
\file
Indicates that a comment block contains documentation for a source or header file with name <name>. The file name may include (part of) the path if the file-name alone is not unique.
So try using \file semLib.c and \file vxWorksApi/semLib.c in the appropriate files.
I had the same issue and making the above change still didn't work:
"So try using \file semLib.c and \file vxWorksApi/semLib.c in the appropriate files."
My situation is different as the files are in separate but parallel folders and this worked for me:
\file xdir/semLib.c and \file ydir/semLib.c in the appropriate files.
For your purposes try adding the full path or a partial path for both:
\file adir/xdir/semLib.c and \file adir/ydir/semLib.c in the appropriate files.
I had the same issue but doesn't help to have only one file changed. You need to have both paths changed