HeaderDocs appear in discussions

[ikkentim]

trafficstars

I tried the following:

/**
 * Returns a collection of available maps.
 * @param error A pointer to a NSError object. This error will be given a value if an error has occurred.
 * @return A collection of available maps.
 */
+ (nullable NSArray<MovinMap*>*)getMaps:(NSError* _Nullable* _Nullable)error;

Generated docs:

Returns a collection of available maps. - parameter: error A pointer to a NSError object. This error will be given a value if an error has occurred. - returns: A collection of available maps.

I obviously do not my parameters/return values to appear there. I've also tried @brief and @abstract, but these end up in the docs:

/**
 * @abstract Returns a collection of available maps.
 * @param error A pointer to a NSError object. This error will be given a value if an error has occurred.
 * @return A collection of available maps.
 */
+ (nullable NSArray<MovinMap*>*)getMaps:(NSError* _Nullable* _Nullable)error;

@abstract Returns a collection of available maps. - parameter: error A pointer to a NSError object. This error will be given a value if an error has occurred. - returns: A collection of available maps.

Also, @code ... @endcode does not appear to work? To be honest, I haven't found any HeaderDocs to be working, even though the readme claims a (limited) number of HeaderDocs keywords are supported.

Am I doing something wrong or did something break?

/ I think this is related to #673

[istx25]

(someone correct me if I'm wrong but) I don't believe Jazzy supports all of the keywords. I'll do some digging and come back to you with what I find.

[jpsim]

Try newline between directives:

/**
 * Returns a collection of available maps.
 *
 * @param error A pointer to a NSError object. This error will be given a value if an error has occurred.
 *
 * @return A collection of available maps.
 */
+ (nullable NSArray<MovinMap*>*)getMaps:(NSError* _Nullable* _Nullable)error;

[mikelehen]

We ran into this as well. It'd be nice if Jazzy was a little more tolerant of newlines being absent.

[ikkentim]

Also, would love support for @code ... @endcode, I dug into the code and it seems jazzy doesn't support it.

I ended up using a few quick regex replaces to add newlines into my comments and format code blocks like so:

`@code
// code here
@endcode`

and then replace these before letting jazzy do it's job:

find build/docs -type f -exec sed -i '' 's/\* @code/\* ``` objc/g' {} +
find build/docs -type f -exec sed -i '' 's/\* @endcode/\* ```/g' {} +

[johnfairh]

Newline tolerance in #413; the @code thing was added to sourcekitten in the past few years.