Cover Foundation / UIKit extensions in documentation comments

[Mark Pospesel]

Intro

In our generated documentation, the top-level pages for extensions look very sparse. Like this:

By adding documentation comments to public extensions, we could improve the readability of both the source code and the generated documentation. The documentation shown above with extension comments added, becomes this:

Task

1. Add documentation comments to the following public extensions:

• Foundation/CGFloat+rounded.swift
• Foundation/CGSize+inset.swift
• Foundation/String+Localizable.swift
• UIKit/UIScreen+scaleFactor.swift
• UIKit/UITraitCollection+colorSpaces.swift
• UIKit/UIView+constrainEdges.swift (NSDirectionalRectEdge extension only)

2. Unify how we declare these extensions: move the public declaration to the extension itself and remove it from the individual public methods (any properties/methods declared as internal/private need to remain so) Do this only for the extensions you document in Step 1 above

AC

• Task (above) completed
• 0 SwiftLint violations
• compiles with 0 warnings for iOS and tvOS
• unit tests pass for iOS and tvOS
• 100% documentation coverage as per Jazzy

Discussion

Jazzy combines all extended properties / methods from multiple extensions into a single documentation page. e.g. for UIColor we have 8 properties / methods spread across 5 separate extensions but they are all documented together on a single page. In this case Jazzy will not generate documentation for the extension (how would it know to combine the comments from the 5 extensions?). Documenting the extensions still has value though, but for now we will focus on classes that only have a single extension in our package. In a later ticket we can document the multiple extensions for UIColor, UIView, etc.