objc doc generation: "fatal error: not text: CXCommentKind(rawValue: 3)"

[Nelyus]

I encountered this error while trying to generate documentation for an all-objc framework with jazzy.

tl;dr; don't use html tags, use markdown

I don't know if it is worth addressing, but at least the explanation and workaround might be worth this ticket. (It took me some time to understand where the error came from).

The issue error arises when some fields in the documentation contains an html tag. So the workaround is to remove html tags and prefer markdown.

For information here is the header file, command line args and error log of the failing case:

// my_header.h

/**
 * some foo function
 * @param bar has a <b>purpose</b>
 */
void foo(int bar);

$> sourcekitten doc --objc my_header.h -- -x objective-c -isysroot "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk -I '' -fmodules
fatal error: not text: CXCommentKind(rawValue: 3): file /[...]/SourceKitten/Source/SourceKittenFramework/Clang+SourceKitten.swift, line 263

but the following works fine:

// my_header.h

/**
 * some foo function
 * @param bar has a **purpose**
 */
void foo(int bar);