0

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.

albert
  • 8,285
  • 3
  • 19
  • 32
Julian B.
  • 3,605
  • 2
  • 29
  • 38
  • 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 Mar 06 '15 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. Mar 09 '15 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 Mar 10 '15 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 Mar 12 '15 at 03:25
  • Content of headers will not be documented if you use C++ keywords like `not` in your preprocessor directives. Bug filed here: https://github.com/doxygen/doxygen/issues/9172 – not-a-user Feb 28 '22 at 09:58

3 Answers3

2

"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
*/
Joe
  • 21
  • 2
1

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.

Phil
  • 5,822
  • 2
  • 31
  • 60
  • Thanks Phil! I'm sorry, that was a typo on my end. I do have the additional asterisk. already updated question. – Julian B. Mar 06 '15 at 16:50
  • 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? – Julian B. Mar 12 '15 at 18:29
  • 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. – albert Mar 12 '15 at 19:26
  • 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! – Phil Mar 12 '15 at 21:28
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".

David I
  • 881
  • 6
  • 10
  • 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 May 04 '21 at 11:19
  • 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 May 04 '21 at 11:23
  • 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? – albert May 06 '21 at 07:58
  • 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. – David I May 08 '21 at 11:19
  • 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`).). – albert May 08 '21 at 12:13
  • Done. See https://github.com/doxygen/doxygen/issues/8539 – David I May 08 '21 at 12:36
  • As discussed in the github issue: https://github.com/doxygen/doxygen/issues/8539 some essential information is missing in this answer i.e. the fact that theer are subsequent lines in the `@file` block that have a different (less spaces) indentation. – albert May 08 '21 at 15:28
  • Thanks to albert for pointing out that the unindented 4th line causes the previous lines to be treated as `@verbatim`. The verbatim feature of markdown seems stronger in v1.9 than it was in v1.8, because it all worked fine in v.1.8.3. After examining the output of my much larger doxygen HTML output I found more cases where the `@verbatim` behaviour had occurred and messed up the output (which again had worked perfectly in v1.8.3). As a result I would strongly recommend against using *ANY* indentations for Doxygen markup, except where you actually want verbatim text. – David I May 10 '21 at 09:13
  • I know that we moved the markdown handling at one stage so the handling was easier and more consistent withing doxygen. It had some side effects and this might have been one of them. – albert May 10 '21 at 09:25