From 51898748596b2c7f1cda32f043f7808124b693a9 Mon Sep 17 00:00:00 2001 From: Randall Wood <297232+rhwood@users.noreply.github.com> Date: Sun, 2 Jul 2023 19:23:08 -0400 Subject: [PATCH] doc: refactor code comments --- Sources/WMATAUI/Font+Extension.swift | 15 ++++---- Sources/WMATAUI/LineUI.swift | 22 ++++++------ Sources/WMATAUI/WMATAUI.docc/WMATAUI.md | 6 ++++ Sources/WMATAUI/WMATAUI.swift | 48 ++++++++++++------------- Sources/WMATAUI/WMATAUIFont.swift | 12 ++++--- 5 files changed, 53 insertions(+), 50 deletions(-) diff --git a/Sources/WMATAUI/Font+Extension.swift b/Sources/WMATAUI/Font+Extension.swift index 22f8bf4..63c0805 100644 --- a/Sources/WMATAUI/Font+Extension.swift +++ b/Sources/WMATAUI/Font+Extension.swift @@ -8,14 +8,14 @@ import SwiftUI import WMATA +/// Functions to return the WMATA standard font. public extension Font { /// The WMATA standard font with the given style. The WMATA style guide stipulates the use of Helvetica Neue. /// Note that station signage uses multiple variations of Helvetica for different signage. - /// - /// - Parameter style: The font style. - /// - Parameter factor: Factor by which to multiply default font size for style; defaults to `1.0`. - /// + /// - Parameters: + /// - style: The font style. + /// - factor: Factor by which to multiply default font size for style; defaults to `1.0`. /// - Returns: The WMATA standard font in the given style. @available(iOS 14.0, *) @available(macCatalyst 14.0, *) @@ -26,10 +26,9 @@ public extension Font { /// The WMATA standard font with the given size. The WMATA style guide stipulates the use of Helvetica Neue. /// Note that station signage uses multiple variations of Helvetica for different signage. - /// - /// - Parameter size: The font size. - /// - Parameter relativeTo: Style the font size resizes relative to when user overrides system default sizes; defaults to `.body`. - /// + /// - Parameters: + /// - size: The font size. + /// - relativeTo: Style the font size resizes relative to when user overrides system default sizes; defaults to `.body`. /// - Returns: The WMATA standard font in the given size. @available(iOS 14.0, *) @available(macCatalyst 14.0, *) diff --git a/Sources/WMATAUI/LineUI.swift b/Sources/WMATAUI/LineUI.swift index b00f293..88be715 100644 --- a/Sources/WMATAUI/LineUI.swift +++ b/Sources/WMATAUI/LineUI.swift @@ -8,7 +8,7 @@ import SwiftUI import WMATA -/// SwiftUI dependent extensions to Line +/// SwiftUI dependent extensions to ``Line``. public extension Line { /// The line color. @@ -30,7 +30,7 @@ public extension Line { } /// The text color (white or black) that contrasts with the line color. - /// These colors match the colors used by WMATA on their public maps, but do match the colors used by Apple in Maps on iOS 15. + /// These colors match the colors used by WMATA on their public maps, but do not match the colors used by Apple in Maps. var textColor: Color { switch self { case .red, .blue, .green: @@ -41,10 +41,9 @@ public extension Line { } /// Get a textless dot in the line color sized for the given text style. - /// - /// - Parameter style: The style to match. - /// - Parameter factor: Optional factor to multiply the point size of the style by, defaults to 0.9. - /// + /// - Parameters: + /// - style: The style to match. + /// - factor: Optional factor to multiply the point size of the style by, defaults to 0.9. /// - Returns: A circle in in the color of this line sized to match the text style. @available(macOS 11.0, iOS 14.0, *) func dot(style: Font.TextStyle, factor: CGFloat = 0.9) -> some View { @@ -54,10 +53,9 @@ public extension Line { /// Get a dot in the line color containing the two letter line code and sized for the given text style. /// /// To get a roundel where the line code text size matches the style size, use a factor of `2.0`. - /// - /// - Parameter style: The style to match. - /// - Parameter factor: Optional factor to multiply the point size of the style by; defaults to `1.0`. - /// + /// - Parameters: + /// - style: The style to match. + /// - factor: Optional factor to multiply the point size of the style by; defaults to `1.0`. /// - Returns: A circle in the color of this line sized to match the text style with the line code in a smaller text size. @available(iOS 14.0, *) @available(macCatalyst 14.0, *) @@ -67,10 +65,10 @@ public extension Line { } } -/// Conformance with Comparable +/// Conformance with ``Comparable``. extension Line: Comparable { - /// Sort an array of Line by the order shown in the Metrorail map legend + /// Sort an array of ``Line`` by the order shown in the Metrorail map legend. public static func < (lhs: Line, rhs: Line) -> Bool { allCases.firstIndex(of: lhs)! < allCases.firstIndex(of: rhs)! } diff --git a/Sources/WMATAUI/WMATAUI.docc/WMATAUI.md b/Sources/WMATAUI/WMATAUI.docc/WMATAUI.md index 198da6a..045df32 100644 --- a/Sources/WMATAUI/WMATAUI.docc/WMATAUI.md +++ b/Sources/WMATAUI/WMATAUI.docc/WMATAUI.md @@ -4,3 +4,9 @@ A SwiftUI library for the Washington Metropolitan Area Transit Authority brandin WMATAUI is a companion to (and depends upon) [WMATA.swift](https://emma-k-alexandra.github.io/WMATA.swift/documentation/wmata/). +## Topics + +### Color +This library includes extensions to ``Color`` that encode the WMATA branding colors. +- ``Color`` +- ``LineUI`` diff --git a/Sources/WMATAUI/WMATAUI.swift b/Sources/WMATAUI/WMATAUI.swift index a834be5..c6519ff 100644 --- a/Sources/WMATAUI/WMATAUI.swift +++ b/Sources/WMATAUI/WMATAUI.swift @@ -12,11 +12,10 @@ import WMATA public struct WMATAUI { /// Get a color dot sized for the given text style. - /// - /// - Parameter color: The dot's color. - /// - Parameter style: The style to match. - /// - Parameter factor: Optional factor to multiply the point size of the style by; defaults to `0.9`. - /// + /// - Parameters: + /// - color: The dot's color. + /// - style: The style to match. + /// - factor: Optional factor to multiply the point size of the style by; defaults to `0.9`. /// - Returns: A circle in in the given color sized to match the text style. @available(macOS 11.0, iOS 14.0, *) public static func dot(color: Color, style: Font.TextStyle, factor: CGFloat = 0.9) -> some View { @@ -28,13 +27,12 @@ public struct WMATAUI { /// Get a color dot sized for the given text style with a smaller text within it. This really works only for one or two character strings. /// /// To get a roundel where the line code text size matches the style size, use a factor of `2.0`. - /// - /// - Parameter text: The text to display. - /// - Parameter color: The color of the dot. - /// - Parameter textColor: The color of the text in the dot. - /// - Parameter style: The style to match. - /// - Parameter factor: Optional factor to multiply the point size of the style by; defaults to `1.0`. - /// + /// - Parameters: + /// - text: The text to display. + /// - color: The color of the dot. + /// - textColor: The color of the text in the dot. + /// - style: The style to match. + /// - factor: Optional factor to multiply the point size of the style by; defaults to `1.0`. /// - Returns: A circle in in the given color sized to match the text style with the given text in a smaller size. @available(iOS 14.0, *) @available(macCatalyst 14.0, *) @@ -50,13 +48,12 @@ public struct WMATAUI { /// Get a color dot sized for the given text style with an image within it. This really works only for symbols. /// /// To get a roundel where the line code text size matches the style size, use a factor of `2.0`. - /// - /// - Parameter image: The image to display. - /// - Parameter color: The color of the dot. - /// - Parameter textColor: The color of the text in the dot. - /// - Parameter style: The style to match. - /// - Parameter factor: Optional factor to multiply the point size of the style by; defaults to `1.0`. - /// + /// - Parameters: + /// - image: The image to display. + /// - color: The color of the dot. + /// - textColor: The color of the text in the dot. + /// - style: The style to match. + /// - factor: Optional factor to multiply the point size of the style by; defaults to `1.0`. /// - Returns: A circle in in the given color sized to match the text style with the given image in a smaller size. @available(iOS 14.0, *) @available(macCatalyst 14.0, *) @@ -72,13 +69,12 @@ public struct WMATAUI { /// Get a color dot sized for the given view. This really works only for symbols or one or two character strings. /// /// To get a roundel where the line code text size matches the style size, use a factor of `2.0`. - /// - /// - Parameter view: The view to display. - /// - Parameter color: The color of the dot. - /// - Parameter textColor: The color of the text in the dot. - /// - Parameter style: The style to match. - /// - Parameter factor: Optional factor to multiply the point size of the style by; defaults to `1.0`. - /// + /// - Parameters: + /// - view: The view to display. + /// - color: The color of the dot. + /// - textColor: The color of the text in the dot. + /// - style: The style to match. + /// - factor: Optional factor to multiply the point size of the style by; defaults to `1.0`. /// - Returns: A circle in in the given color sized to match the text style with the given view in a smaller size. @available(iOS 14.0, *) @available(macCatalyst 14.0, *) diff --git a/Sources/WMATAUI/WMATAUIFont.swift b/Sources/WMATAUI/WMATAUIFont.swift index 8ad2e53..33bc503 100644 --- a/Sources/WMATAUI/WMATAUIFont.swift +++ b/Sources/WMATAUI/WMATAUIFont.swift @@ -7,11 +7,11 @@ #if os(macOS) import AppKit -/// Opaque reference to NSFont or UIFont depending on use of AppKit or UIKit. +/// Opaque reference to NSFont (macOS) or UIFont (everything else including macOS Catalyst). public typealias WMATAUIFont = NSFont #else import UIKit -/// Opaque reference to NSFont or UIFont depending on use of AppKit or UIKit. +/// Opaque reference to NSFont (macOS) or UIFont (everything else including macOS Catalyst). public typealias WMATAUIFont = UIFont #endif import SwiftUI @@ -22,8 +22,12 @@ public extension WMATAUIFont.TextStyle { // rule triggered by tvOS macro, so disabling // swiftlint:disable cyclomatic_complexity - /// Convert a Font.TextStyle to a NSFont.TextStyle (if using AppKit) or UIFont.TextStyle (if using UIKit)) - /// Note that on tvOS, this converts Font.TextStyle.largeTitle the same as Font.TextStyle.title + /// Convert a Font.TextStyle to a ``NSFont.TextStyle`` (on macOS) or ``UIFont.TextStyle`` + /// (on everything else including macOS Catalyst). + /// + /// Note that on tvOS, this converts ``Font.TextStyle.largeTitle`` the same as ``Font.TextStyle.title``. + /// - Parameter textStyle: the ``Font.TextStyle`` to convert. + /// - Returns: The corresponding ``WMATAUIFont.TextStyle`` for the given textStyle. static func with(textStyle: Font.TextStyle) -> WMATAUIFont.TextStyle { let style: WMATAUIFont.TextStyle