Tools: HeaderDoc User's Guide: Unexpected Behavior

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

© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-10-27)