chapter_9_section_2.html [plain text]
<html>
<head>
<META NAME="Generator" CONTENT="Gutenberg">
<META NAME="GeneratorVersion" CONTENT="v103.5
">
<META http-equiv="content-type" CONTENT="text/html;charset=iso-8859-1">
<META NAME = "Copyright" CONTENT="Copyright 2004 Apple Computer, Inc. All Rights Reserved.">
<META NAME="IndexTitle" CONTENT="Common Error Messages">
<TITLE>Tools: HeaderDoc User's Guide: Common Error Messages</TITLE>
<base target="content">
<LINK REL="stylesheet" TYPE="text/css" HREF="../Resources/CSS/frameset_styles.css">
<style type="text/css"></style>
<script language="JavaScript" src="../Resources/JavaScript/page.js"></script>
</head>
<BODY bgcolor="#ffffff" onload="initialize_page();"><a name="//apple_ref/doc/uid/TP40001215-CH366-DontLinkElementID_44" title="Common Error Messages" turn_anchor="no"></a>
<a name="top"></a>
<!-- start of header -->
<!--#include virtual="/includes/framesetheader" -->
<!-- end of header -->
<!-- start of path -->
<div class="breadcrumb"><a href="http://developer.apple.com/" target="_top">ADC Home</a> > <!--a logicalPath="//apple_ref/doc/uid/TP30000943" -->Reference Library<!--/a--> > <!--a logicalPath="//apple_ref/doc/uid/TP30000440" -->Documentation<!--/a--> > <!--a logicalPath="//apple_ref/doc/uid/TP30000436" -->Tools<!--/a--> > <!--a logicalPath="//apple_ref/doc/uid/TP30000436-TP30000502" -->Darwin<!--/a--> > <a logicalPath="//apple_ref/doc/uid/TP40001215-CH345" href="../intro/chapter_1_section_1.html#//apple_ref/doc/uid/TP40001215-CH345">HeaderDoc User's Guide</a> > <a logicalPath="//apple_ref/doc/uid/TP40001215-CH366" href="chapter_9_section_1.html#//apple_ref/doc/uid/TP40001215-CH366">Troubleshooting</a> > </div><br>
<!-- end of path -->
<table width="100%" cellpadding=0 cellspacing=0 border=0 class="mini_nav_text"><tr>
<td align=left scope="row">
<!-- insert Show/Hide frames -->
<script type="text/javascript" language="JavaScript"><!--
if (self != top) {
document.write('<a href="'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="'+self.location+'" target="_top">Hide TOC</a>');
}
else {
document.write('<a href="../index.html?'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="../index.html?'+self.location+'" target="_top">Show TOC</a>');
}
<!-- end Show/Hide frames -->
</td><td align=right>
<a href="chapter_9_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_9_section_3.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<a name="DontLinkElementID_44" title="Common Error Messages" turn_anchor="no"></a><h2>Common Error Messages</h2>
<ul class="simple"><li><b>Q:</b> When running
gatherheaderdoc, I get an error from something called resolveLinks
that says “I/O error: encoder error”. What’s going on?</li>
<li><b>A:</b> You have a header file
that was not written in UTF-8. Change the encoding for that file by
adding an <tt>@encoding</tt> or
<tt>@charset</tt> entry within
the <tt>@header</tt> tag.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
keeps warning me that my LibXML2 version is too old. How do I fix
this problem?</li>
<li><b>A:</b> Obtain a more recent
version of LibXML2 from <span class="content_text"><a href="http://www.xmlsoft.org" target="_top">http://www.xmlsoft.org</a></span>.</li></ul>
<ul class="simple"><li><b>Q:</b> I’m trying
to do an @link to a method, but HeaderDoc insists that myMethodname%58 could
not be found.</li>
<li><b>A:</b> Beginning in HeaderDoc
8.5, you should use colons in the names of methods in @link tags,
rather than replacing them with %58.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
is choking on classes with multiple inheritance.</li>
<li><b>A:</b> Update to HeaderDoc 8.5.</li></ul>
<ul class="simple"><li><b>Q:</b> Why isn’t
HeaderDoc doing C preprocessing? I thought you said this version
did.</li>
<li><b>A:</b> It does, but you have
to specify an additional flag, <tt>-p</tt>,
to invoke this behavior.</li></ul>
<ul class="simple"><li><b>Q:</b> The C preprocess
keeps including the wrong files.</li>
<li><b>A:</b> 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.</li></ul>
<ul class="simple"><li><b>Q:</b> I keep getting
the error “Name being changed (oldname -> newname).”</li>
<li><b>A:</b> This is usually caused
by one of the following:
<ul class="simple"><li>1. Multiple @discussion blocks. Remove
one of them.</li>
<li>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.</li></ul></li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
says “Can’t open <filename> for availability macros.”</li>
<li><b>A:</b> Your installation is
likely missing the <code>Availability.list</code> file.
It should normally live in <code>/System/Library/Perl/version/HeaderDoc</code>.</li></ul>
<ul class="simple"><li><b>Q:</b> I’m getting
the error “Conflicting declarations for function/method ($name1)
outside a class. This is probably not what you want.”</li>
<li><b>A:</b> 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.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
is spewing warnings about “Parsed parameter <blah> not found
in declaration of function/method/typedef <blah>.”</li>
<li><b>A:</b> Chances are, you made
a typographical error when adding <tt>@param</tt> or
<tt>@field</tt> markers in the
HeaderDoc comment. Check your spelling carefully and remember that capitalization
matters.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
keeps saying “Tagged parameter <blah> not found in declaration
of function/method/typedef <blah>.”</li>
<li><b>A:</b> You turned on the strict
parameter/field checking with the <tt>-t</tt> flag.
Turn it off if you don’t want those warnings.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
says “Braces/class braces/parentheses/square braces do not match.
We may have a problem.”</li>
<li><b>A:</b> 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.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
says “End of parse tree reached while searching for matching definition”.</li>
<li><b>A:</b> 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 <tt>typedef</tt> with
an <tt>@function</tt> comment).</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
says “No matching declaration found. Last name was <blah>.”</li>
<li><b>A:</b> 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 <tt>typedef</tt> with
an <tt>@function</tt> comment).</li></ul>
<ul class="simple"><li><b>Q:</b> I’m getting
the error “Unable to process #define macro “<name>.”</li>
<li><b>A:</b> Please file a bug.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
says “WARNING: multiple matches found for symbol “<blah>.”
Only the first matching symbol will be linked.”</li>
<li><b>A:</b> You have multiple symbols
with the same name (possibly in different files, or possibly different
types—for example a function and a <tt>#define</tt>).
HeaderDoc has no way to know which of those two or more “myname”
symbols you’re talking about when you say <tt>@link
myname</tt>. To fix this problem, look in the HeaderDoc-generated
HTML for the desired destination. Find the name anchor that looks
like <tt><a name=”instead of just giving the name, give the entire contents of that
anchor.</li></ul>
<ul class="simple"><li><b>Q:</b> 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).’</li>
<li><b>A:</b> 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 <tt><a name=”instead of just giving the name, give the entire contents of that
anchor.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
issues the warning “WARNING: resolveLinks not installed. Please
check your installation.”</li>
<li><b>A:</b> Be sure you are installing
correctly. First, type “<tt>make</tt>”,
then “<tt>make realinstall</tt>”.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
says “WARNING: Unexpected headerdoc markup found in <blah> declaration.”</li>
<li><b>A:</b> Chances are, you followed
one HeaderDoc comment with another HeaderDoc comment without anything
in-between.</li></ul>
<ul class="simple"><li><b>Q:</b> Headerdoc
warns “Unterminated @link tag (starting field was: @link...).”</li>
<li><b>A:</b> If you are using JavaDoc-style
@link tagging (<tt>{@link symbol Link Text}</tt>),
don’t forget the close curly brace. If you are doing HeaderDoc-style
@link tagging (<tt>@link symbol Link Text @/link</tt>),
don’t forget the <tt>@/link</tt>.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
said “Parser bug: empty outer type.”</li>
<li><b>A:</b> 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.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
keeps saying “Objective-C method found outside a class or interface
(or in a class or interface that lacks HeaderDoc markup).”</li>
<li><b>A:</b> Make sure you properly
tagged the enclosing class or interface declaration.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
keeps saying “Unable to find parse tree. Please file a bug.”</li>
<li><b>A:</b> This should not happen;
please file a bug.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
keeps saying “Couldn’t find parser state. Using slow method.”</li>
<li><b>A:</b> If you have a class that
starts with a preprocessor token (such as <tt>DeclareStructors(MyClass)</tt> or
similar), this will break things badly. There are two solutions.
The easiest solution is to add <tt>@ignorefuncmacro
DeclareStructors</tt> (or whatever the macro name
happens to be) in your <tt>@header</tt> declaration.</li>
<li> 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
<tt>-p</tt> flag. Finally, add
a HeaderDoc comment before the macro definition.</li>
<li> If this problem is not caused by use of a macro,
please file a bug. This fallback case should not affect output,
however.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
keeps saying ‘Could not determine include file name for “#include FW(Carbon,CarbonEvents.h)”’
or similar.</li>
<li><b>A:</b> Ideally, you should use
a standard include file syntax. If that is not possible, you should enable
the C preprocessor with the <tt>-p</tt> flag,
include the file containing the FW macro on the command line, and
add HeaderDoc markup to that macro.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
says “Unknown regexp delimiter “...”. Please file a bug.</li>
<li><b>A:</b> This should not happen;
please file a bug.</li></ul>
<ul class="simple"><li><b>Q:</b> HeaderDoc
keeps saying “Unknown keyword <blah> in block-parsed declaration”.</li>
<li><b>A:</b> Make sure that the header
compiles correctly with <tt>gcc</tt>.
If it does, please file a bug.</li></ul>
<p>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....</p>
<ul class="simple"><li><b>Q:</b> How do I
file a bug?</li>
<li><b>A:</b> 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 <span class="content_text"><a href="http://lists.apple.com/mailman/listinfo/headerdoc-dev" target="_top">http://lists.apple.com/mailman/listinfo/headerdoc-dev</a></span>.</li>
<li> 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”.</li>
<li> If not, please visit <span class="content_text"><a href="http://www.opendarwin.org" target="_top">http://www.opendarwin.org</a></span> and
file a bug report in the HeaderDoc component through Bugzilla.</li></ul>
<br><br>
<table width="100%" cellpadding=0 cellspacing=0 border=0 class="mini_nav_text"><tr>
<td align=left scope="row">
<!-- insert Show/Hide frames -->
<script type="text/javascript" language="JavaScript"><!--
if (self != top) {
document.write('<a href="'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="'+self.location+'" target="_top">Hide TOC</a>');
}
else {
document.write('<a href="../index.html?'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="../index.html?'+self.location+'" target="_top">Show TOC</a>');
}
<!-- end Show/Hide frames -->
</td><td align=right>
<a href="chapter_9_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_9_section_3.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<br><hr><div align="center"><p class="content_text"> <!--#if expr="0=1" -->© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (<!--#endif -->Last updated: 2004-10-27<!--#if expr="0=1" -->)<!--#endif --></p></div>
<!-- start of footer -->
<!--#include virtual="/includes/framesetfooter" -->
<!-- end of footer -->
</BODY>
</html>