Unable to Document Header File with Doxygen

Question

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.

The (edited) supplied code does work for me with a default Doxyfile. From the comment with the answer from Phil it is not clear if the problem is solved or not. If not please specify what is still going wrong, does doxygen give errors? — albert
– albert, Commented Mar 6, 2015 at 19:17
@albert - i'm still experiencing problems. i am not getting doxygen to generate any docs for a header file that does not contain the objective c @class directives. what else could i try? — Julian B.
– Julian B., Commented Mar 9, 2015 at 15:39
Please create a small example showing the problem including Doxyfile and post this as an attachment (preferably also with the result output and the console output) either here or in the doxygen users mailing list (see manual chapter troubleshooting for the list) — albert
– albert, Commented Mar 10, 2015 at 19:57
I rewrote my answer below. (I am not sure if I should have done that or just provided a new answer.) — Phil
– Phil, Commented Mar 12, 2015 at 3:25
Content of headers will not be documented if you use C++ keywords like not in your preprocessor directives. Bug filed here: github.com/doxygen/doxygen/issues/9172 — not-a-user
– not-a-user, Commented Feb 28, 2022 at 9:58

Phil · Accepted Answer · 2015-03-12 03:24:29Z

2

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.

edited Mar 12, 2015 at 3:24

answered Mar 6, 2015 at 16:06

Phil

6,2843 gold badges34 silver badges65 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

Julian B. Over a year ago

Thanks Phil! I'm sorry, that was a typo on my end. I do have the additional asterisk. already updated question.

Julian B. Over a year ago

thanks so much! that seemed to do it. i did not enter a value for the INPUT field. so i guess this is auto-populated after setting some other values. why does this work?

albert Over a year ago

Doxygen will probably not find any INPUT files and thus just generates and empty document. In your console output you will probably not seen any files being processed. From where the INPUT = /Users/jlnbuiles/Desktop/test-doxy comes is hard to guess, maybe from an earlier test and you reloaded the Doxyfile.

Phil Over a year ago

leaving input= blank means doxygen will search the current directory. If you want to search other directories, you will have to put paths here. I try to always use relative directories so the config file is usable anywhere. As for where the incorrect absolute path came from, my guess is that it got there when you ran doxywizard. I find it best to read through the config file to make sure it is doing what you want. It is well documented. Good luck!

Joe · Accepted Answer · 2019-11-07 08:50:49Z

1

"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
*/

answered Nov 7, 2019 at 8:50

Joe

192 bronze badges

1 Comment

albert Over a year ago

OP has @file in his file so how can this be the answer?

David I · Accepted Answer · 2021-05-10 09:08:03Z

0

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".

edited May 10, 2021 at 9:08

answered May 4, 2021 at 11:12

David I

9517 silver badges13 bronze badges

9 Comments

albert Over a year ago

What is the output you get? What goes wrong ? The possible cause of your problem might be that your comment block start with 4 spaces and this might be seen as the beginning of a verbatim block.

albert Over a year ago

When using an default Doxyfile I get for both instances the same output! So something in your settings might be the problem, please clarify us (use doxygen -x Doxyfile to show differences in Doxyfile compared to the default version).

albert Over a year ago

We don't know what is in doxygen-footer.html and doxygen-layout.xml but I don't think that that their content matters, so for my tests I commeted them out. Running the test cases gives in both cases the same, correct, result. Do you have somewhere tabs in your file or white space at the end of the line?

David I Over a year ago

I have 5 or six projects I do exactly the same operation with (make doc for just the marked-up .h file), and have done so for years without a problem. Have just tested with another project that worked perfectly with doxygen 1.8 and earlier. Now I've updated to v1.9 it gives me the exactly the same problem and the the same fix works.

albert Over a year ago

Remains very strange, maybe you should create an issue in the doxygen github bug tracker. A small suspicion is that there are some warnings that are ignored or that in the source file are some hidden characters that don't show up here on stack. (The standard text for the github issue: - Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent. - Please also specify the full doxygen version used (doxygen -v).).

|

Collectives™ on Stack Overflow

Unable to Document Header File with Doxygen

3 Answers 3

4 Comments

1 Comment

9 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

4 Comments

1 Comment

9 Comments

Your Answer

Sign up or log in

Post as a guest

Related