landonf/objectdoc — pull request #3 by mattstevens (2013-08-19 03:29:26+00:00)
Title: Initial support for cursors

Most comments are again taken from libclang with edits for consistency and adaptation to the Objective-C API.

Both null and invalid cursors result in nil being returned from the PLClangCursor initializer. While invalid cursors in libclang use their kind to indicate error conditions, the current conditions all mean that what you requested does not exist. In Objective-C nil communicates this and supports an API contract of returning either a valid cursor object or nil. It's possible that these error conditions will expose more useful information in the future though, so if support for invalid cursors is desired it should probably be put in now since it will impact how the related cursor properties are validated (nil vs an "isValid" property check).

Related cursor objects are created upon request rather than in the initializer. This is because the related cursor functions may return the same CXCursor. For example, the canonical cursor for the canonical cursor of a declaration is itself. In addition, the semantic parent of a parameter cursor is its function declaration, and if the arguments array is created in the initializer this also leads to infinite recursion.

Fetching in the initializer may need to be revisited for performance reasons anyway, as a program may create a large number of cursors but only be interested in a subset of the information from most of them (typically just the kind if filtering).

When a libclang translation unit is disposed all objects derived from it (cursors, comments, locations, and tokens) become invalid and any further operations on them are likely to cause a crash. While the CXTranslationUnit could be set up such that all derivative objects kept a reference to an object that managed its lifetime, reparsing a translation unit also invalidates all existing derivative objects. Because of this I'm inclined to say that clients just need to keep a strong reference to the translation unit while they're using something derived from it.

clang_isCursorDefinition is not exposed because the definition property being non-nil provides the same information.

Contains epic enum mapping.