Skip to content

Commit

Permalink
doc: refactor code comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@rhwood
rhwood committed Jul 2, 2023
1 parent 40e1fe6 commit 5189874
Show file tree
Hide file tree
Showing 5 changed files with 53 additions and 50 deletions.
15 changes: 7 additions & 8 deletions Sources/WMATAUI/Font+Extension.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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, *)
Expand All @@ -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, *)
Expand Down
22 changes: 10 additions & 12 deletions Sources/WMATAUI/LineUI.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
import SwiftUI
import WMATA

/// SwiftUI dependent extensions to Line
/// SwiftUI dependent extensions to ``Line``.
public extension Line {

/// The line color.
Expand All @@ -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:
Expand All @@ -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 {
Expand All @@ -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, *)
Expand All @@ -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)!
}
Expand Down
6 changes: 6 additions & 0 deletions Sources/WMATAUI/WMATAUI.docc/WMATAUI.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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``
48 changes: 22 additions & 26 deletions Sources/WMATAUI/WMATAUI.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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, *)
Expand All @@ -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, *)
Expand All @@ -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, *)
Expand Down
12 changes: 8 additions & 4 deletions Sources/WMATAUI/WMATAUIFont.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down

0 comments on commit 5189874

Please sign in to comment.