Add documentation for each parser and it's output. (#24)

* Add documentation for each parser and it's output. * changelog entry * Some extra docs * small typo * font: document new path property * Small bit of info to solve actool issue * Improved Assets documentation clarity + Example * Improved README and add links to documentation markdown files * Nitpickings in documentation * Update Strings documentation * Shorten comment length to make SwiftLint happy ;)
SwiftGen · May 7, 2017 · 903c9be · 903c9be
1 parent aaedfda
commit 903c9be
Show file tree

Hide file tree

Showing 12 changed files with 247 additions and 31 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -33,6 +33,9 @@ _None_
   [David Jennes](https://github.com/djbe)
   [#10](https://github.com/SwiftGen/SwiftGenKit/issues/10)
   [#28](https://github.com/SwiftGen/SwiftGenKit/issues/28)
+* Documented the input & output of each parser.  
+  [David Jennes](https://github.com/djbe)
+  [#24](https://github.com/SwiftGen/SwiftGenKit/issues/24)
 
 ## 1.0.1
 

diff --git a/Documentation/Assets.md b/Documentation/Assets.md
@@ -0,0 +1,87 @@
+# Asset Catalog parser
+
+## Input
+
+The assets parser accepts one (or more) asset catalogs, which it'll parse using the `actool` utility. For now it only parses `image set`s and folders.
+
+Note: there is a bug in `actool` where it won't be able to parse a catalog if it contains certain types of assets, see [here](https://github.com/SwiftGen/SwiftGen/issues/228). The best solution (for now) is to split your asset catalog into multiple ones, and to run SwiftGen on the catalog(s) with supported types.
+
+## Output
+
+The output context has the following structure:
+
+ - `catalogs`: `Array` — list of asset catalogs
+   - `name`  : `String` — the name of the catalog
+   - `assets`: `Array` — tree structure of items, each item either
+     - represents a folder and has the following entries:
+       - `name` : `String` — name of the folder
+       - `items`: `Array` — list of items, can be either folders or images
+     - represents an image asset, and has the following entries:
+       - `name` : `String` — name of the image
+       - `value`: `String` — the actual full name for loading the image
+
+## Example
+
+```
+{
+  "catalogs": [
+    {
+      "name": "Images",
+      "assets": [
+        {
+          "name": "Exotic",
+          "items": [
+            {
+              "value": "Exotic\/Banana",
+              "name": "Banana"
+            },
+            {
+              "value": "Exotic\/Mango",
+              "name": "Mango"
+            }
+          ]
+        },
+        {
+          "value": "Logo",
+          "name": "Logo"
+        },
+        {
+          "name": "Round",
+          "items": [
+            {
+              "value": "Round\/Apricot",
+              "name": "Apricot"
+            },
+            {
+              "value": "Round\/Orange",
+              "name": "Orange"
+            },
+            {
+              "name": "Red",
+              "items": [
+                {
+                  "value": "Round\/Apple",
+                  "name": "Apple"
+                },
+                {
+                  "name": "Double",
+                  "items": [
+                    {
+                      "value": "Round\/Double\/Cherry",
+                      "name": "Cherry"
+                    }
+                  ]
+                },
+                {
+                  "value": "Round\/Tomato",
+                  "name": "Tomato"
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
diff --git a/Documentation/Colors.md b/Documentation/Colors.md
@@ -0,0 +1,21 @@
+# Colors parser
+
+## Input
+
+The colors parser supports multiple input file types:
+
+ - CLR: NSColorList palette file ([see docs](https://developer.apple.com/reference/appkit/nscolorlist)). When you create color palettes in image editors or in Xcode, these are stored in `~/Library/Colors`.
+ - JSON: Simple root object where each key is the name, each value is a hex color string.
+ - TXT: Each line has a name and a color, separated by a `:`. A color can either be a color hex value, or the name of another color in the file.
+ - XML: Android colors.xml file parser ([see docs](https://developer.android.com/guide/topics/resources/more-resources.html#Color)).
+
+## Output
+
+The output context has the following structure:
+
+ - `colors`: `Array` — list of colors:
+    - `name` : `String` — name of the color
+    - `red`  : `String` — hex value of the red component
+    - `green`: `String` — hex value of the green component
+    - `blue` : `String` — hex value of the blue component
+    - `alpha`: `String` — hex value of the alpha component
diff --git a/Documentation/Fonts.md b/Documentation/Fonts.md
@@ -0,0 +1,16 @@
+# Fonts parser
+
+## Input
+
+The fonts parser accepts a directory, which it'll recursively search for font files. Supported file types depend on the target platform, for example iOS only supports TTF and OTF font files.
+
+## Output
+
+The output context has the following structure:
+
+ - `families`: `Array` — list of font families
+   - `name` : `String` — name of the font family
+   - `fonts`: `Array` — list of fonts in the font family
+     - `name` : `String` — the font's postscript name
+     - `path` : `String` — the path to the font, relative to the folder being scanned
+     - `style`: `String` — the designer's description of the font's style, like "bold", "oblique", …
diff --git a/Documentation/Storyboards.md b/Documentation/Storyboards.md
@@ -0,0 +1,28 @@
+# Storyboards parser
+
+## Input
+
+The storyboards parser accepts either a file or a directory, which it'll search for `storyboard` files. The parser will load all the scenes and all the segues for each storyboard. It supports both AppKit (macOS) and UIKit (iOS, watchOS, tvOS) storyboards. 
+
+## Output
+
+The output context has the following structure:
+
+ - `modules`    : `Array<String>` — List of modules used by scenes and segues — typically to be used for "import" statements
+ - `storyboards`: `Array` — List of storyboards
+    - `name`: `String` — Name of the storyboard
+    - `initialScene`: `Dictionary` (absent if not specified)
+       - `customClass` : `String` — The custom class of the scene (absent if generic UIViewController/NSViewController)
+       - `customModule`: `String` — The custom module of the scene (absent if no custom class)
+       - `baseType`: `String` — The base class type of the scene if not custom (absent if class is a custom class).
+          Possible values include 'ViewController', 'NavigationController', 'TableViewController'…
+    - `scenes`: `Array` (absent if empty)
+       - `identifier` : `String` — The scene identifier
+       - `customClass`: `String` — The custom class of the scene (absent if generic UIViewController/NSViewController)
+       - `customModule`: `String` — The custom module of the scene (absent if no custom class)
+       - `baseType`: `String` — The base class type of the scene if not custom (absent if class is a custom class).
+          Possible values include 'ViewController', 'NavigationController', 'TableViewController'…
+    - `segues`: `Array` (absent if empty)
+       - `identifier`: `String` — The segue identifier
+       - `customClass`: `String` — The custom class of the segue (absent if generic UIStoryboardSegue)
+       - `customModule`: `String` — The custom module of the segue (absent if no custom segue class)
diff --git a/Documentation/Strings.md b/Documentation/Strings.md
@@ -0,0 +1,46 @@
+# Strings parser
+
+## Input
+
+The strings parser accepts a `strings` file, typically `Localizable.strings`. It will parse each string in this file, including the type information for formatting parameters. 
+
+The strings file will be converted into a structured tree version, where each string is separated into components by the `.` character. We call this the `dot syntax`, each component representing a level. For example, the following strings:
+
+```
+"some.deep.structure"
+"some.deep.something"
+"hello.world"
+```
+
+will be parsed into the following structure (not showing the rest of the structure, such as values and types):
+
+```swift
+[
+  "some": [
+    "deep": [
+      "structure",
+      "something"
+    ]
+  ],
+  "hello": [
+    "world"
+  ]
+]
+```
+
+## Output
+
+The output context has the following structure:
+
+ - `tables`: `Array` — List of string tables
+   - `name`   : `String` — name of the `.strings` file (usually `"Localizable"`)
+   - `strings`: `Array` — Tree structure of strings (based on dot syntax), each level has:
+     - `name`   : `String` — name of the level (that is, part of the key split by `.` that we're describing)
+     - `strings`: `Array` — list of strings at this level:
+       - `key`: `String` — the full translation key, as it appears in the strings file
+       - `translation`: `String` — the translation for that key in the strings file
+       - `types`: `Array<String>` — defined only if localized string has parameter placeholders like `%d` and `%@` etc.
+          Contains a list of types like `"String"`, `"Int"`, etc
+       - `keytail`: `String` — contains only the last part of the key (after the last `.`)
+         (useful to do recursion when splitting keys against `.` for structured templates)
+     - `subenums`: `Array` — list of sub-levels, repeating the structure mentioned above
diff --git a/README.md b/README.md
@@ -5,4 +5,20 @@
 [![Platform](https://img.shields.io/cocoapods/p/SwiftGenKit.svg?style=flat)](http://cocoadocs.org/docsets/SwiftGenKit)
 ![Swift 3.0](https://img.shields.io/badge/Swift-3.0-orange.svg)
 
-The framework behind SwiftGen, responsible for parsing various resources and turn them into Stencil contexts
+This is the framework behind _SwiftGen_, responsible for parsing various resources and turn them into Stencil contexts
+
+## Context
+
+This framework contains various resource parsers (especially parsers for images, Localizable strings files, fonts, color palettes, storyboards, …) which are responsible for providing a dictionary representation of those resources suitable to be used by a template engine like [Stencil](https://github.com/kylef/Stencil).
+
+THe goal of this framework is to be used by Code Generation tools like SwiftGen to turn those resources into some internal representation that can then be used to generate custom code from it.
+
+## Documentation
+
+Each parser provided by this framework has a corresponding documentation file explaining the expected input and the format of the generated output, so you can know how to exploit it:
+
+* [Assets](Documentation/Assets.md)
+* [Colors](Documentation/Colors.md)
+* [Fonts](Documentation/Fonts.md)
+* [Storyboards](Documentation/Storyboards.md)
+* [Strings](Documentation/Strings.md) 
diff --git a/Sources/Stencil/AssetsCatalogContext.swift b/Sources/Stencil/AssetsCatalogContext.swift
@@ -9,13 +9,13 @@ import Foundation
 /*
  - `catalogs`: `Array` — list of asset catalogs
    - `name`  : `String` — the name of the catalog
-   - `assets`: `Array` — tree structure of items, each item is either a:
-     - group: this represents a folder
-		- `name` : `String` — name of the folder
-        - `items`: `Array` — list of items, can be either groups or images
-     - image: this represents an image asset
-        - `name` : `String` — name of the image
-        - `value`: `String` — the actual name for loading the image
+   - `assets`: `Array` — tree structure of items, each item either
+     - represents a folder and has the following entries:
+       - `name` : `String` — name of the folder
+       - `items`: `Array` — list of items, can be either folders or images
+     - represents an image asset, and has the following entries:
+       - `name` : `String` — name of the image
+       - `value`: `String` — the actual full name for loading the image
 */
 extension AssetsCatalogParser {
   public func stencilContext(enumName: String = "Asset") -> [String: Any] {

diff --git a/Sources/Stencil/ColorsContext.swift b/Sources/Stencil/ColorsContext.swift
@@ -30,8 +30,8 @@ extension ColorsFileParser {
         "alpha": comps[3],
 
         // NOTE: This is a deprecated variable
-		"rgba": String(hexChars[0..<8]),
-		"rgb": String(hexChars[0..<6])
+        "rgba": String(hexChars[0..<8]),
+        "rgb": String(hexChars[0..<6])
       ]
     }).sorted { $0["name"] ?? "" < $1["name"] ?? "" }
 

diff --git a/Sources/Stencil/FontsContext.swift b/Sources/Stencil/FontsContext.swift
@@ -8,11 +8,11 @@ import Foundation
 
 /*
  - `families`: `Array` — list of font families
-   - `name` : `String` — name of family
-   - `fonts`: `Array` — list of fonts in family
+   - `name` : `String` — name of the font family
+   - `fonts`: `Array` — list of fonts in the font family
      - `name` : `String` — the font's postscript name
      - `path` : `String` — the path to the font, relative to the folder being scanned
-     - `style`: `String` — the designer's description of the font's style, like bold, oblique, …
+     - `style`: `String` — the designer's description of the font's style, like "bold", "oblique", …
 */
 
 extension FontsFileParser {

diff --git a/Sources/Stencil/StoryboardsContext.swift b/Sources/Stencil/StoryboardsContext.swift
@@ -14,25 +14,24 @@ private func uppercaseFirst(_ string: String) -> String {
 }
 
 /*
- - `modules`    : `Array<String>` — List of modules used by scenes and segues
+ - `modules`    : `Array<String>` — List of modules used by scenes and segues — typically used for "import" statements
  - `storyboards`: `Array` — List of storyboards
     - `name`: `String` — Name of the storyboard
     - `initialScene`: `Dictionary` (absent if not specified)
-       - `customClass` : `String` (absent if generic UIViewController/NSViewController)
-       - `customModule`: `String` (absent if no custom class)
-       - `baseType`: `String` (absent if class is a custom class).
-          The base class type on which the initial scene is base.
+       - `customClass` : `String` — The custom class of the scene (absent if generic UIViewController/NSViewController)
+       - `customModule`: `String` — The custom module of the scene (absent if no custom class)
+       - `baseType`: `String` — The base class type of the scene if not custom (absent if class is a custom class).
           Possible values include 'ViewController', 'NavigationController', 'TableViewController'…
     - `scenes`: `Array` (absent if empty)
-       - `identifier` : `String`
-       - `customClass`: `String` (absent if generic UIViewController/NSViewController)
-       - `customModule`: `String` (absent if no custom class)
-       - `baseType`: `String` (absent if class is a custom class).
-          The base class type on which a scene is base.
+       - `identifier` : `String` — The scene identifier
+       - `customClass`: `String` — The custom class of the scene (absent if generic UIViewController/NSViewController)
+       - `customModule`: `String` — The custom module of the scene (absent if no custom class)
+       - `baseType`: `String` — The base class type of the scene if not custom (absent if class is a custom class).
           Possible values include 'ViewController', 'NavigationController', 'TableViewController'…
     - `segues`: `Array` (absent if empty)
-       - `identifier`: `String`
-       - `customClass`: `String` (absent if generic UIStoryboardSegue)
+       - `identifier`: `String` — The segue identifier
+       - `customClass`: `String` — The custom class of the segue (absent if generic UIStoryboardSegue)
+       - `customModule`: `String` — The custom module of the segue (absent if no custom segue class)
 */
 extension StoryboardParser {
   public func stencilContext(sceneEnumName: String = "StoryboardScene",

diff --git a/Sources/Stencil/StringsContext.swift b/Sources/Stencil/StringsContext.swift
@@ -18,13 +18,13 @@ private extension String {
  - `tables`: `Array` — List of string tables
    - `name`   : `String` — name of the `.strings` file (usually `"Localizable"`)
    - `strings`: `Array` — Tree structure of strings (based on dot syntax), each level has:
-     - `name`   : `String` — name of the level
+     - `name`   : `String` — name of the level (that is, part of the key split by `.` that we're describing)
      - `strings`: `Array` — list of strings at this level:
-       - `key`: `String` — the full translation key
-       - `translation`: `String` — the translated text
-       - `types`: `Array<String>` — defined only if localized string has parameters.
-          Containing types like `"String"`, `"Int"`, etc
-       - `keytail`: `String` containing the rest of the key after the next first `.`
+       - `key`: `String` — the full translation key, as it appears in the strings file
+       - `translation`: `String` — the translation for that key in the strings file
+       - `types`: `Array<String>` — defined only if localized string has parameter placeholders like `%d` and `%@` etc.
+          Contains a list of types like `"String"`, `"Int"`, etc
+       - `keytail`: `String` — contains only the last part of the key (after the last `.`)
          (useful to do recursion when splitting keys against `.` for structured templates)
      - `subenums`: `Array` — list of sub-levels, repeating the structure mentioned above
 */