Hi.
I'm writing a framework, and invest a lot in commenting classes, methods, etc. My API is Objective-C, but the issue is same with Swift code too.
If I follow Apple's documentation about the Markup language of code-comments, then in Xcode QuickHelp lot of my formatting simply does not show.
Here are Apple docs on the matter
Here is a sample of class definition comment,
/*!
@brief Comprehensive set of prevention rules.
@discussion OITPreventionSettings instance encapsulates a complete set of prevention "rules" dictated and provided by Backend, controlling the behavior of ITProtector.
At any moment, there can only be a single "ruling" instance of OITPreventionSettings, assigned (synchronously and atomically) to the OITPrevention, while other instances may exist in other states of initialization/demise.
Responsibilities of the class:
* Receive and store a "Settings JSON" from backend (either as File, String or NSDictionary)
* Parse the settings JSON, extract relevant policy clauses, parse their array of prevention rules
* Provide comprehensive parsing errors if rules cannot be applied.
* Compile and own a hierarchy of OITPreventionPolicy and OITPreventionRule objects, with internal representation of the rules, that can be used to fast-decide authorization/prevention events.
* Apply rules to Endpoint-Security event, returning both verdict (actions bit-mask), and the rule-Id responsible for the decision.
Irresponsibilities of the class:
* to decide *when* to become the "active" settings
* to apply itself and evaluate ES events
* Being immutable, It can't change its policies and rules nor their internal representations. Any change of settings require a new instance of OITPreventionSettings.
*/
@interface OITPreventionSettings : NSObject {
}
As you can see in the attached Xcode quick-help window screenshot
, none of the lists appear as lists, and even line-breaks don't apply.
Many other formatting rules don't show either. Is this Apple bug? my misunderstanding? what's the point in documenting something that doesn't and actually never worked?