I'm attempting to generate documentation for a header file that just contains some constants and I'm not able to generate it.
As suggested in the doxygen manual, I've tried adding the #file keyword to a comment block and still no luck.
What am I missing?
Here's a snippet:
MyFile.h
/**
#file
my super important documentation.
#author Julian Builes
*/
typedef NS_ENUM(NSUInteger, HTTPCode)
{my code ...}
background: it's an iOS project using xcode 6 and doxygen 1.8.9.1
EDIT: As per Albert's suggestion, I'm attaching a sample project that exemplifies the problem I'm experiencing.
"Files are considered private by default. This means files that do not have the #file declaration (or \file) are ignored and not included in your Doxygen output, except for members of C++ classes."
Ref: https://linux.m2osw.com/doxygen-does-not-generate-documentation-my-c-functions-or-any-global-function
Put the following at the top of your header:
/**
\file
*/
I believe you have an error in your Doxyfile configuration file. Just leave the "INPUT =" line blank, and doxygen will search the current directory for the source files matching the patterns you specify. When you change that, among the doxygen output you should see
...
Parsing files
Preprocessing C:/temp/doxy test/TEDHTTPStatusCodes.h...
Parsing file C:/temp/doxy test/TEDHTTPStatusCodes.h...
And you should see the "Files" tab populated on your doxygen generated main page.
If this is any help (using v1.9.1), it seems the #file (\file) declaration must be right up against the left margin. I spent hours wondering why one particular .h file would not work.
So this is OK:
/**
#file
#brief My superb interface
#par Note re foo bar
Functions that output to the szFoo buffer use the throgglethorp algorithm.
*/
But this is not, with the #file indented
/**
#file
#brief Not so good
#par Note re foo bar
Functions that output to the szFoo buffer use the throgglethorp algorithm.
*/
# Difference with default Doxyfile 1.9.1 (ef9b20ac7f8a8621fcfc299f8bd0b80422390f4b)
PROJECT_NAME = MyProject
PROJECT_NUMBER = 9.3.0
OUTPUT_DIRECTORY = doxy
ABBREVIATE_BRIEF =
FULL_PATH_NAMES = NO
JAVADOC_AUTOBRIEF = YES
QT_AUTOBRIEF = YES
OPTIMIZE_OUTPUT_FOR_C = YES
SHOW_INCLUDE_FILES = NO
SORT_BRIEF_DOCS = YES
SHOW_USED_FILES = NO
SHOW_NAMESPACES = NO
LAYOUT_FILE = doxygen-layout.xml
INPUT = src/myIncludeFile.h
INPUT_ENCODING = ISO-8859-1
FILE_PATTERNS =
EXAMPLE_PATTERNS =
VERBATIM_HEADERS = NO
ALPHABETICAL_INDEX = NO
HTML_FOOTER = doxygen-footer.html
HTML_TIMESTAMP = YES
MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
GENERATE_LATEX = NO
LATEX_CMD_NAME = latex
SEARCH_INCLUDES = NO
DOT_FONTNAME =
With the second instance (indented #file) the result is an html file with nothing documented. With the first instance, I get the result I want, which is the html/my_include_file_8h.html with subtitle "myIncludeFile.h File Reference".
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 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
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.