Cassowary: improve some documentation coverage

This cleans up some of the markers and adds a trivial amount of documentation coverage.

Sources/Cassowary/Constraint.swift

@@ -9,9 +9,15 @@ public extension Constraint {
   }
 }
 
+/// Describes a constraint over variables in the system.
 public class Constraint {
+  /// The expression that is constrained.
   public let expression: Expression
+
+  /// The relationship between the expression and the constant.
   public let operation: Constraint.Relationship
+
+  /// The strength of the constraint.
   public let strength: Strength
 
   public init(_ expression: Expression, _ operation: Constraint.Relationship,
@@ -28,6 +34,8 @@ public class Constraint {
   }
 }
 
+// MARK: - Hashable
+
 extension Constraint: Hashable {
   public func hash(into hasher: inout Hasher) {
     hasher.combine(expression)
@@ -36,6 +44,8 @@ extension Constraint: Hashable {
   }
 }
 
+// MARK: - Equatable
+
 extension Constraint: Equatable {
   public static func == (lhs: Constraint, rhs: Constraint) -> Bool {
     return lhs.expression == rhs.expression &&
@@ -44,6 +54,8 @@ extension Constraint: Equatable {
   }
 }
 
+// MARK: - CustomStringConvertible
+
 extension Constraint: CustomStringConvertible {
   public var description: String {
     var value: String = expression.terms.reduce("") {

Sources/Cassowary/Errors.swift

@@ -1,58 +1,71 @@
 // Copyright © 2019 Saleem Abdulrasool <compnerd@compnerd.org>.
 // SPDX-License-Identifier: BSD-3-Clause
 
+/// The constraint cannot be satisfied.
 public struct UnsatisfiableConstraint: Error {
   private let constraint: Constraint
   public init(_ constraint: Constraint) {
     self.constraint = constraint
   }
 }
 
+// MARK: - CustomStringConvertible
+
 extension UnsatisfiableConstraint: CustomStringConvertible {
   public var description: String {
     return "unable to satisfy constraint: \(constraint)"
   }
 }
 
+/// The constraint is not currently in the system.
 public struct UnknownConstraint: Error {
   private let constraint: Constraint
   public init(_ constraint: Constraint) {
     self.constraint = constraint
   }
 }
 
+// MARK: - CustomStringConvertible
+
 extension UnknownConstraint: CustomStringConvertible {
   public var description: String {
     return "unknown constraint: \(constraint)"
   }
 }
 
+/// The constraint is already in the system.
 public struct DuplicateConstraint: Error {
   private let constraint: Constraint
   public init(_ constraint: Constraint) {
     self.constraint = constraint
   }
 }
 
+// MARK: - CustomStringConvertible
+
 extension DuplicateConstraint: CustomStringConvertible {
   public var description: String {
     return "duplicate constraint: \(constraint)"
   }
 }
 
+/// The edit variable is not in the system.
 public struct UnknownEditVariable: Error {
   public init(_ variable: Variable) {
   }
 }
 
+/// The edit variable is already in the system.
 public struct DuplicateEditVariable: Error {
   public init(_ variable: Variable) {
   }
 }
 
+/// The required strength is invalid.
 public struct BadRequiredStrength: Error {
 }
 
+/// An internal solver error occurred.
 internal struct InternalSolverError: Error {
   public init(_ message: String) {
   }

Sources/Cassowary/Expression.swift

@@ -4,8 +4,12 @@
 @_implementationOnly
 import OrderedCollections
 
+/// An expression is a linear combination of terms and a constant.
 public struct Expression {
+  /// The terms of the expression.
   public let terms: [Term]
+
+  /// The constant of the expression.
   public let constant: Double
 
   public var value: Double {
@@ -27,13 +31,17 @@ public struct Expression {
   }
 }
 
+// MARK: - Hashable
+
 extension Expression: Hashable {
   public func hash(into hasher: inout Hasher) {
     hasher.combine(terms)
     hasher.combine(constant)
   }
 }
 
+// MARK: - Equatable
+
 extension Expression: Equatable {
   public static func == (lhs: Expression, rhs: Expression) -> Bool {
     return lhs.terms == rhs.terms && lhs.constant == rhs.constant

Sources/Cassowary/Row.swift

@@ -120,6 +120,8 @@ internal class Row {
   }
 }
 
+// MARK: - CustomStringConvertible
+
 extension Row: CustomStringConvertible {
   public var description: String {
     return cells.reduce("\(constant)") {

Sources/Cassowary/Solver.swift

@@ -576,6 +576,8 @@ public class Solver {
   }
 }
 
+// MARK: - CustomStringConvertible
+
 extension Solver: CustomStringConvertible {
   public var description: String {
     return """

Sources/Cassowary/Symbol.swift

@@ -37,12 +37,17 @@ extension Symbol: Comparable {
   }
 }
 
+// MARK: - Hashable
+
 extension Symbol: Hashable {
   public func hash(into hasher: inout Hasher) {
     hasher.combine(id)
     hasher.combine(type)
   }
 }
+
+// MARK: - CustomStringConvertible
+
 extension Symbol: CustomStringConvertible {
   public var description: String {
     switch type {

Sources/Cassowary/Symbolics.swift

@@ -1,15 +1,16 @@
 // Copyright © 2019 Saleem Abdulrasool <compnerd@compnerd.org>.
 // SPDX-License-Identifier: BSD-3-Clause
 
-// MARK - epsilon check
+// MARK: - epsilon check
 
 infix operator ~=
+
 public func ~= (_ lhs: Double, _ rhs: Double) -> Bool {
   let epsilon: Double = 1.0e-8
   return abs(lhs - rhs) <= epsilon
 }
 
-// MARK - expression operations
+// MARK: - expression operations
 
 public prefix func - (_ expression: Expression) -> Expression {
   return expression * -1.0
@@ -56,7 +57,7 @@ public func / (_ expression: Expression, _ denominator: Double) -> Expression {
   return expression * (1.0 / denominator)
 }
 
-// MARK - term operations
+// MARK: - term operations
 
 public prefix func - (_ term: Term) -> Term {
   return term * -1.0
@@ -102,7 +103,7 @@ public func / (_ term: Term, _ denominator: Double) -> Term {
   return term * (1.0 / denominator)
 }
 
-// MARK - variable operations
+// MARK: - variable operations
 
 public prefix func - (_ variable: Variable) -> Term {
   return variable * -1.0
@@ -148,7 +149,7 @@ public func / (_ variable: Variable, _ denominator: Double) -> Term {
   return variable * (1.0 / denominator)
 }
 
-// MARK - double operations
+// MARK: - double operations
 
 public func + (_ lhs: Double, _ rhs: Expression) -> Expression {
   return rhs + lhs
@@ -186,7 +187,7 @@ public func * (_ coefficient: Double, _ variable: Variable) -> Term {
   return variable * coefficient
 }
 
-// MARK - expression constraints
+// MARK: - expression constraints
 
 public func == (_ lhs: Expression, _ rhs: Expression) -> Constraint {
   return Constraint(lhs - rhs, .eq)
@@ -236,7 +237,7 @@ public func >= (_ lhs: Expression, _ rhs: Double) -> Constraint {
   return lhs >= Expression(rhs)
 }
 
-// MARK - term constraints
+// MARK: - term constraints
 
 public func == (_ lhs: Term, _ rhs: Expression) -> Constraint {
   return rhs == lhs
@@ -286,7 +287,7 @@ public func >= (_ lhs: Term, _ rhs: Double) -> Constraint {
   return Expression(lhs) >= rhs
 }
 
-// MARK - Variable constraints
+// MARK: - Variable constraints
 
 public func == (_ lhs: Variable, _ rhs: Expression) -> Constraint {
   return rhs == lhs
@@ -336,7 +337,7 @@ public func >= (_ lhs: Variable, _ rhs: Double) -> Constraint {
   return Term(lhs) >= rhs
 }
 
-// MARK - double constraints
+// MARK: - double constraints
 
 public func == (_ lhs: Double, _ rhs: Expression) -> Constraint {
   return rhs == lhs
@@ -374,7 +375,7 @@ public func >= (_ lhs: Double, _ rhs: Variable) -> Constraint {
   return rhs <= lhs
 }
 
-// MARK - constraint strength modifiers
+// MARK: - constraint strength modifiers
 
 @available(*, deprecated, message: "explicitly pass strength when adding the constraint")
 public func | (_ lhs: Constraint, _ rhs: Strength) -> Constraint {

Sources/Cassowary/Term.swift

@@ -15,13 +15,17 @@ public class Term {
   }
 }
 
+// MARK: - Hashable
+
 extension Term: Hashable {
   public func hash(into hasher: inout Hasher) {
     hasher.combine(variable)
     hasher.combine(coefficient)
   }
 }
 
+// MARK: - Equatable
+
 extension Term: Equatable {
   public static func == (lhs: Term, rhs: Term) -> Bool {
     return lhs.variable == rhs.variable && lhs.coefficient == rhs.coefficient

Sources/Cassowary/Variable.swift

@@ -11,12 +11,16 @@ public class Variable {
   }
 }
 
+// MARK: - Hashable
+
 extension Variable: Hashable {
   public func hash(into hasher: inout Hasher) {
     hasher.combine(name)
   }
 }
 
+// MARK: - Equatable
+
 extension Variable: Equatable {
   public static func == (lhs: Variable, rhs: Variable) -> Bool {
     return lhs.name == rhs.name && lhs.value == rhs.value