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)