This chapter explains how to troubleshoot HeaderDoc issues, including explanations of error messages, in the form of a Q&A list.
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 file a bug through that mechanism. The correct component is “HeaderDoc”, with version “Darwin”.
Q:I’m seeing multiple copies of my functions/typedefs/defines/*. Why?
A:You probably specified a name in the @function tag (or @typedef or...) that was different from the actual name.
Q:I’m still seeing multiple copies of a typedef, but with different names.
A:HeaderDoc, by default, also generates an entry for “tag names” and for every type name. You can remove the tag names by specifying the -O (outer names only) flag. In the following example, the tag name is mystruct, and the type name (a.k.a. the “outer name”) is mystruct_t:
typedef struct mystruct {int a;} mystruct_t; |
Q:Why does my function/method/type/variable/class/* have a name that appears to include an entire paragraph of the discussion?
A:One of two things is wrong. Either you included multiple words after the @function/@typedef/@whatever and also included an @discussion tag or you began a multi-line declaration at the end of the @function/@typedef/@whatever line. Don’t do this. See “Multiword Names” for more information.
Q:A bunch of my functions/typedefs/* are being linked together with “See Also” attributes. What’s up?
A:You probably marked a typedef with an @function comment (or some other incorrect pairing). HeaderDoc will assume that you knew what you were doing and will keep looking through the code until it finds whatever was requested (a function in this case). Everything in-between will get linked together. The purpose for this is primarily to allow you to mark @typedef for a struct followed by a typedef, but it is useful in other situations as well. Fix the incorrectly matched comment, and the problem should go away.
Q:Why am I not getting links when I add @link tags?
A:There are several possible reasons:
1.If you used apple_ref markup, you may have made a typo.
2.If you used a symbol name that did not exist, you would get a warning when running headerdoc2html and no link will be generated.
3.The @link tag only inserts a link request into the HTML. To turn this into an actual link, you must run gatherheaderdoc (which in turn runs resolveLinks to create the links). Until you run gatherHeaderDoc, all you will see in the HTML are a bunch of specially-formatted comments.
Q:Every time I run gatherheaderdoc, all of the spaces in my declarations go away. What’s going on?
A:This is a bug in libxml2 that is fixed in more recent versions. Please visit http://www.xmlsoft.org to obtain a more recent version (or upgrade to Mac OS X 10.4 or later).
Q:I’m confused. Where can I get help?
A:The best place to get help is the HeaderDoc-dev mailing list. To subscribe, go to http://lists.apple.com/mailman/listinfo/headerdoc-dev.
Last updated: 2009-11-17
