Tools: HeaderDoc User's Guide: Common Error Messages

## Common Error Messages

- Q: When running gatherheaderdoc, I get an error from something called resolveLinks that says “I/O error: encoder error”. What’s going on?
- A: You have a header file that was not written in UTF-8. Change the encoding for that file by adding an `@encoding` or `@charset` entry within the `@header` tag.

- Q: HeaderDoc keeps warning me that my LibXML2 version is too old. How do I fix this problem?
- A: Obtain a more recent version of LibXML2 from http://www.xmlsoft.org.

- Q: I’m trying to do an @link to a method, but HeaderDoc insists that myMethodname%58 could not be found.
- A: Beginning in HeaderDoc 8.5, you should use colons in the names of methods in @link tags, rather than replacing them with %58.

- Q: HeaderDoc is choking on classes with multiple inheritance.
- A: Update to HeaderDoc 8.5.

- Q: Why isn’t HeaderDoc doing C preprocessing? I thought you said this version did.
- A: It does, but you have to specify an additional flag, `-p`, to invoke this behavior.

- Q: The C preprocess keeps including the wrong files.
- A: HeaderDoc has no way of knowing the final installed location of header files. To work correctly, it depends on all header files having a unique name. Rename your header files so that no two files have exactly the same name.

- Q: I keep getting the error “Name being changed (oldname -> newname).”
- A: This is usually caused by one of the following:
  - 1. Multiple @discussion blocks. Remove one of them.
  - 2. An extra preprocessor macro token after the close parenthesis in a function declaration. HeaderDoc thinks you are writing a K&R C declaration. Either use @ignore to ignore the token or explicitly mark up the preprocessor macro and enable C preprocessing.

- Q: HeaderDoc says “Can’t open <filename> for availability macros.”
- A: Your installation is likely missing the `Availability.list` file. It should normally live in `/System/Library/Perl/version/HeaderDoc`.

- Q: I’m getting the error “Conflicting declarations for function/method ($name1) outside a class. This is probably not what you want.”
- A: As it says, you have two functions that are not class members, but have the same name (or you forgot to put HeaderDoc markup on the enclosing class). This is legal in C++ but is discouraged because the apple_ref syntax does not provide a uniqueness guarantee in these instances. HeaderDoc tries to fudge this by appending a signature when it sees this situation, but as a general rule, you should not rely on this behavior if you care about apple_ref markup.

- Q: HeaderDoc is spewing warnings about “Parsed parameter <blah> not found in declaration of function/method/typedef <blah>.”
- A: Chances are, you made a typographical error when adding `@param` or `@field` markers in the HeaderDoc comment. Check your spelling carefully and remember that capitalization matters.

- Q: HeaderDoc keeps saying “Tagged parameter <blah> not found in declaration of function/method/typedef <blah>.”
- A: You turned on the strict parameter/field checking with the `-t` flag. Turn it off if you don’t want those warnings.

- Q: HeaderDoc says “Braces/class braces/parentheses/square braces do not match. We may have a problem.”
- A: This usually means exactly what it says. If you are depending on a C preprocessor macro to make braces match, you should try to avoid doing so. If you cannot avoid this, make sure you enable C preprocessing and add HeaderDoc markup to the macro definition.

- Q: HeaderDoc says “End of parse tree reached while searching for matching definition”.
- A: This is generally caused by either placing a HeaderDoc comment immediately prior to a close curly brace or by placing the wrong HeaderDoc type tag in the comment (such as preceding a `typedef` with an `@function` comment).

- Q: HeaderDoc says “No matching declaration found. Last name was <blah>.”
- A: This is generally caused by either placing a HeaderDoc comment immediately prior to a close curly brace or by placing the wrong HeaderDoc type tag in the comment (such as preceding a `typedef` with an `@function` comment).

- Q: I’m getting the error “Unable to process #define macro “<name>.”
- A: Please file a bug.

- Q: HeaderDoc says “WARNING: multiple matches found for symbol “<blah>.” Only the first matching symbol will be linked.”
- A: You have multiple symbols with the same name (possibly in different files, or possibly different types—for example a function and a `#define`). HeaderDoc has no way to know which of those two or more “myname” symbols you’re talking about when you say `@link myname`. To fix this problem, look in the HeaderDoc-generated HTML for the desired destination. Find the name anchor that looks like `<a name=”//apple_ref/...”>` and instead of just giving the name, give the entire contents of that anchor.

- Q: HeaderDoc says ‘WARNING: no symbol matching “<blah>” found. If this symbol is not in this file or class, you need to specify it with an api ref tag (e.g. apple_ref).’
- A: You may not be processing all of the needed files at once, or HeaderDoc may be feeling cranky. In any case, to fix this problem, look in the HeaderDoc-generated HTML for the desired destination. Find the name anchor that looks like `<a name=”//apple_ref/...”>` and instead of just giving the name, give the entire contents of that anchor.

- Q: HeaderDoc issues the warning “WARNING: resolveLinks not installed. Please check your installation.”
- A: Be sure you are installing correctly. First, type “`make`”, then “`make realinstall`”.

- Q: HeaderDoc says “WARNING: Unexpected headerdoc markup found in <blah> declaration.”
- A: Chances are, you followed one HeaderDoc comment with another HeaderDoc comment without anything in-between.

- Q: Headerdoc warns “Unterminated @link tag (starting field was: @link...).”
- A: If you are using JavaDoc-style @link tagging (`{@link symbol Link Text}`), don’t forget the close curly brace. If you are doing HeaderDoc-style @link tagging (`@link symbol Link Text @/link`), don’t forget the `@/link`.

- Q: HeaderDoc said “Parser bug: empty outer type.”
- A: This is probably a bug unless you’re doing something really weird with preprocessor directives that violate the normal C syntax rules (in which case you should either @ignore the extraneous tokens or enable C preprocessing). In general, though, you should probably file a bug.

- Q: HeaderDoc keeps saying “Objective-C method found outside a class or interface (or in a class or interface that lacks HeaderDoc markup).”
- A: Make sure you properly tagged the enclosing class or interface declaration.

- Q: HeaderDoc keeps saying “Unable to find parse tree. Please file a bug.”
- A: This should not happen; please file a bug.

- Q: HeaderDoc keeps saying “Couldn’t find parser state. Using slow method.”
- A: If you have a class that starts with a preprocessor token (such as `DeclareStructors(MyClass)` or similar), this will break things badly. There are two solutions. The easiest solution is to add `@ignorefuncmacro DeclareStructors` (or whatever the macro name happens to be) in your `@header` declaration.
- An alternative fix is to make sure that you are processing the header file that contains the macro at the same time as you process the class. Enable C preprocessing with the `-p` flag. Finally, add a HeaderDoc comment before the macro definition.
- If this problem is not caused by use of a macro, please file a bug. This fallback case should not affect output, however.

- Q: HeaderDoc keeps saying ‘Could not determine include file name for “#include FW(Carbon,CarbonEvents.h)”’ or similar.
- A: Ideally, you should use a standard include file syntax. If that is not possible, you should enable the C preprocessor with the `-p` flag, include the file containing the FW macro on the command line, and add HeaderDoc markup to that macro.

- Q: HeaderDoc says “Unknown regexp delimiter “...”. Please file a bug.
- A: This should not happen; please file a bug.

- Q: HeaderDoc keeps saying “Unknown keyword <blah> in block-parsed declaration”.
- A: Make sure that the header compiles correctly with `gcc`. If it does, please file a bug.

Other error messages generally fall into one of two categories: self-explanatory errors (such as “Unknown tag @whatever in function comment”) or utterly unintelligible (such as “Parser bug: empty outer type”). In the case of the former, please fix the appropriate declaration. In the case of the latter, pleas file a bug. Which brings us to the last question....

- Q: How do I file a bug?
- A: Before filing a bug, you should subscribe to the HeaderDoc-dev mailing list on lists.apple.com. Ask if anyone else has seen the problem. If not, you should file a bug. To subscribe, visit http://lists.apple.com/mailman/listinfo/headerdoc-dev.
- If you are an ADC member with access to bugreport.apple.com, please log file a bug through that mechanism. The correct component is “HeaderDoc”, with version “Darwin”.
- If not, please visit http://www.opendarwin.org and file a bug report in the HeaderDoc component through Bugzilla.

© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-10-27)