Merge pull request scottrhoyt#16 from scottrhoyt/documentation

Documentation
andreaponza · Jan 1, 2017 · 98c5efa · 98c5efa
2 parents 511d3c2 + e97b057
commit 98c5efa
Show file tree

Hide file tree

Showing 36 changed files with 3,909 additions and 2 deletions.
diff --git a/.swiftlint.yml b/.swiftlint.yml
@@ -1,2 +1,6 @@
 included: Source
+
+disabled_rules:
+  - closure_parameter_position
+
 line_length: 130
diff --git a/README.md b/README.md
@@ -21,6 +21,7 @@ A lightweight Swift library for generating text tables.
 ### Carthage (OS X)
 You can use [Carthage](https://github.com/Carthage/Carthage) to install
 `SwiftyTextTable` by adding it to your `Cartfile`:
+
 ```
 github "scottrhoyt/SwiftyTextTable"
 ```
@@ -29,6 +30,7 @@ github "scottrhoyt/SwiftyTextTable"
 You can use [The Swift Package Manager](https://swift.org/package-manager) to
 install `SwiftyTextTable` by adding the proper description to your
 `Package.swift` file:
+
 ```swift
 import PackageDescription
 
@@ -224,6 +226,10 @@ print(tableString)
 output (e.g. [Rainbow](https://github.com/onevcat/Rainbow)) and account for them
 in constructing the table.
 
+### API Reference
+
+Check out the full API reference [here](https://github.com/scottrhoyt/SwiftyTextTable/blob/master/docs/index.html).
+
 ## License
 
 SwiftyTextTable is released under the [MIT License](https://github.com/scottrhoyt/SwiftyTextTable/blob/master/LICENSE).
diff --git a/Source/SwiftyTextTable/TextTable.swift b/Source/SwiftyTextTable/TextTable.swift
@@ -61,13 +61,21 @@ private extension Array where Element: CustomStringConvertible {
 
 // MARK: - TextTable Protocols
 
+/// A protocol used to create a `TextTable` from an object.
 public protocol TextTableObject {
+
+    /// The text table header.
     static var tableHeader: String? { get }
+
+    /// An array column headers to represent this object's data.
     static var columnHeaders: [String] { get }
+
+    /// The values to render in the text table. Should have the same count as `columnHeaders`.
     var tableValues: [CustomStringConvertible] { get }
 }
 
 public extension TextTableObject {
+    /// Returns `nil`.
     static var tableHeader: String? {
         return nil
     }
@@ -77,37 +85,79 @@ private func fence(strings: [String], separator: String) -> String {
     return separator + strings.joined(separator: separator) + separator
 }
 
+/// Represents a column in a `TextTable`.
 public struct TextTableColumn {
+
+    /// The header for the column.
     public var header: String
+
+    /// The values contained in this column. Each value represents another row.
     fileprivate var values: [String] = []
 
+    /// Initialize a new column for inserting into a `TextTable`.
     public init(header: String) {
         self.header = header
     }
 
+    /** 
+    The minimum width of the column needed to accomodate all values in this column.
+    - Complexity: O(n)
+    */
     public var width: Int {
+        // FIXME: This should probably be a function because of it's O(n) complexity.
         return max(header.strippedLength(), values.reduce(0) { max($0, $1.strippedLength()) })
     }
 }
 
+/// Used to create a tabular representation of data.
 public struct TextTable {
+
+    /// The columns within the table.
     private var columns: [TextTableColumn]
+
+    /// The `String` used to separate columns in the table. Defaults to "|".
     public var columnFence = "|"
+
+    /// The `String` used to separate rows in the table. Defaults to "-".
     public var rowFence = "-"
+
+    /// The `String` used to mark the intersections of a `columnFence` and a `rowFence`. Defaults to "+".
     public var cornerFence = "+"
+
+    /// The table's header text. If set to `nil`, no header will be rendered. Defaults to `nil`.
     public var header: String? = nil
 
+    /**
+    Create a new `TextTable` from `TextTableColumn`s.
+
+    - parameters:
+      - columns: An `Array` of `TextTableColumn`s.
+      - header: The table header. Defaults to `nil`.
+    */
     public init(columns: [TextTableColumn], header: String? = nil) {
         self.columns = columns
         self.header = header
     }
 
+    /**
+    Create a new `TextTable` from an `TextTableObject`s.
+
+    - parameters:
+      - objects: An `Array` of `TextTableObject`s.
+      - header: The table header. Defaults to `nil`.
+    */
     public init<T: TextTableObject>(objects: [T], header: String? = nil) {
         self.header = header ?? T.tableHeader
         columns = T.columnHeaders.map { TextTableColumn(header: $0) }
         objects.forEach { addRow(values: $0.tableValues) }
     }
 
+    /**
+    Add a row to the table.
+
+    - parameters:
+      - values: The values contained in the new row.
+    */
     public mutating func addRow(values: [CustomStringConvertible]) {
         let values = values.count >= columns.count ? values :
             values + [CustomStringConvertible](repeating: "", count: columns.count - values.count)
@@ -119,6 +169,11 @@ public struct TextTable {
         }
     }
 
+    /**
+    Render the table to a `String`.
+
+    - returns: The `String` representation of the table.
+    */
     public func render() -> String {
         let separator = fence(strings: columns.map({ column in
             return repeatElement(rowFence, count: column.width + 2).joined()
@@ -135,6 +190,11 @@ public struct TextTable {
         return [top, columnHeaders, separator, values, separator].paragraph()
     }
 
+    /**
+    Render the table's header to a `String`.
+
+    - returns: The `String` representation of the table header. `nil` if `header` is `nil`.
+    */
     private func renderTableHeader() -> String? {
         guard let header = header else {
             return nil

diff --git a/SwiftyTextTable.xcodeproj/project.pbxproj b/SwiftyTextTable.xcodeproj/project.pbxproj
@@ -129,6 +129,7 @@
 				3B5BDCE21C63133100592068 /* Frameworks */,
 				3B5BDCE31C63133100592068 /* Headers */,
 				3B5BDCE41C63133100592068 /* Resources */,
+				3B3AB4111E19A29B0006D81D /* SwiftLint */,
 			);
 			buildRules = (
 			);
@@ -144,7 +145,6 @@
 			buildConfigurationList = 3B5BDCFD1C63133100592068 /* Build configuration list for PBXNativeTarget "SwiftyTextTableTests" */;
 			buildPhases = (
 				3B5BDCEC1C63133100592068 /* Sources */,
-				3B5BDD0B1C6320C800592068 /* SwiftLint */,
 				3B5BDCED1C63133100592068 /* Frameworks */,
 				3B5BDCEE1C63133100592068 /* Resources */,
 			);
@@ -214,7 +214,7 @@
 /* End PBXResourcesBuildPhase section */
 
 /* Begin PBXShellScriptBuildPhase section */
-		3B5BDD0B1C6320C800592068 /* SwiftLint */ = {
+		3B3AB4111E19A29B0006D81D /* SwiftLint */ = {
 			isa = PBXShellScriptBuildPhase;
 			buildActionMask = 2147483647;
 			files = (

diff --git a/docs/Protocols.html b/docs/Protocols.html
@@ -0,0 +1,120 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Protocols  Reference</title>
+    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
+    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
+    <meta charset="utf-8">
+    <script src="js/jquery.min.js" defer></script>
+    <script src="js/jazzy.js" defer></script>
+
+  </head>
+  <body>
+
+
+    <a title="Protocols  Reference"></a>
+
+    <header class="header">
+      <p class="header-col header-col--primary">
+        <a class="header-link" href="index.html">
+           Docs
+        </a>
+         (100% documented)
+      </p>
+
+
+    </header>
+
+    <p class="breadcrumbs">
+      <a class="breadcrumb" href="index.html"> Reference</a>
+      <img class="carat" src="img/carat.png" />
+      Protocols  Reference
+    </p>
+
+    <div class="content-wrapper">
+      <nav class="navigation">
+        <ul class="nav-groups">
+          <li class="nav-group-name">
+            <a class="nav-group-name-link" href="Protocols.html">Protocols</a>
+            <ul class="nav-group-tasks">
+              <li class="nav-group-task">
+                <a class="nav-group-task-link" href="Protocols/TextTableObject.html">TextTableObject</a>
+              </li>
+            </ul>
+          </li>
+          <li class="nav-group-name">
+            <a class="nav-group-name-link" href="Structs.html">Structs</a>
+            <ul class="nav-group-tasks">
+              <li class="nav-group-task">
+                <a class="nav-group-task-link" href="Structs/TextTable.html">TextTable</a>
+              </li>
+              <li class="nav-group-task">
+                <a class="nav-group-task-link" href="Structs/TextTableColumn.html">TextTableColumn</a>
+              </li>
+            </ul>
+          </li>
+        </ul>
+      </nav>
+      <article class="main-content">
+
+        <section class="section">
+          <div class="section-content">
+            <h1>Protocols</h1>
+            <p>The following protocols are available globally.</p>
+
+          </div>
+        </section>
+
+        <section class="section">
+          <div class="section-content">
+            <div class="task-group">
+              <div class="task-name-container">
+                <a name="/TextTable%20Protocols"></a>
+                <a name="//apple_ref/swift/Section/TextTable Protocols" class="dashAnchor"></a>
+                <a href="#/TextTable%20Protocols">
+                  <h3 class="section-name">TextTable Protocols</h3>
+                </a>
+              </div>
+              <ul class="item-container">
+                <li class="item">
+                  <div>
+                    <code>
+                    <a name="/s:P15SwiftyTextTable15TextTableObject"></a>
+                    <a name="//apple_ref/swift/Protocol/TextTableObject" class="dashAnchor"></a>
+                    <a class="token" href="#/s:P15SwiftyTextTable15TextTableObject">TextTableObject</a>
+                    </code>
+                  </div>
+                  <div class="height-container">
+                    <div class="pointer-container"></div>
+                    <section class="section">
+                      <div class="pointer"></div>
+                      <div class="abstract">
+                        <p>A protocol used to create a <code><a href="Structs/TextTable.html">TextTable</a></code> from an object.</p>
+
+                        <a href="Protocols/TextTableObject.html" class="slightly-smaller">See more</a>
+                      </div>
+                      <div class="declaration">
+                        <h4>Declaration</h4>
+                        <div class="language">
+                          <p class="aside-title">Swift</p>
+                          <pre class="highlight"><code><span class="kd">public</span> <span class="kd">protocol</span> <span class="kt">TextTableObject</span></code></pre>
+
+                        </div>
+                      </div>
+                    </section>
+                  </div>
+                </li>
+              </ul>
+            </div>
+          </div>
+        </section>
+
+      </article>
+    </div>
+    <section class="footer">
+      <p>&copy; 2017 <a class="link" href="" target="_blank" rel="external"></a>. All rights reserved. (Last updated: 2017-01-01)</p>
+      <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.7.3</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
+    </section>
+  </body>
+</div>
+</html>