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.