Unexpected Behavior

• 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.