SerailizablePathExplorer doc

Also finished « Getting started »

Package.swift

@@ -55,7 +55,7 @@ let package = Package(
             name: "ScoutCLTCore",
             dependencies: [
                 "Scout", "Parsing"]),
-        .target(
+        .executableTarget(
             name: "ScoutCLT",
             dependencies: [
                 "Scout",

Sources/Scout/Models/Path/Path.swift

@@ -5,7 +5,7 @@
 
 import Foundation
 
-/// Collection of `PathElement`s to subscript a `PathExplorer`
+/// Collection of ``PathElement``s to subscript a `PathExplorer`
 public struct Path: Hashable {
 
     // MARK: - Constants

Sources/Scout/Models/PathExplorer/SerializablePathExplorer.swift

@@ -22,11 +22,13 @@ public protocol SerializablePathExplorer: PathExplorer {
     ///
     /// - note: The single values will be exported correspondingly to the data format.
     /// For instance: `<string>Hello</string>` and not  `Hello`.
-    /// To get only the value of the `PathExplorer` without the data , use `description`
+    /// To get only the value of the `PathExplorer` without the format , use `description`
     /// or the corresponding type (e.g. `pathExplorer.int` or `pathExplorer.bool`)
     func exportString() throws -> String
 
-    /// Export the path explorer value to a CSV if possible. Use the default separator ';' if none specified
+    /// Export the path explorer value to a CSV if possible, using the provided separator.
+    ///
+    /// - note: Not all values are exportable to CSV. For instance, a three dimensions array is not exportable, neither an array of heterogeneous dictionaries.
     func exportCSV(separator: String?) throws -> String
 
     /// Export the path explorer value to the specified format data with a default root name "root"
@@ -35,7 +37,14 @@ public protocol SerializablePathExplorer: PathExplorer {
     /// Export the path explorer value to the specified format string data with a default root name "root"
     func exportString(to format: DataFormat, rootName: String?) throws -> String
 
-    /// Returns a new explorer from the provided CSV string when it's possible. Throws otherwise.
+    /// Returns a new explorer from the provided CSV string when it's possible.
+    /// - Parameters:
+    ///     - string: The CSV as `String`
+    ///     - separator: The `Character` used as separator in the CSV string
+    ///     - hasHeaders: Specify whether the CSV string has named headers. Named headers can be full ``Path``s to structure the explorer
+    ///
+    /// - Returns: A `SerializablePathExplorer` from the provided CSV
+    /// - Throws: If the CSV cannot be converted to Self
     static func fromCSV(string: String, separator: Character, hasHeaders: Bool) throws -> Self
 
     /// New explorer replacing the group values (array or dictionaries) sub values by a unique one
@@ -44,15 +53,22 @@ public protocol SerializablePathExplorer: PathExplorer {
     func folded(upTo level: Int) -> Self
 
     /// Folded explored description, replacing the group values (array or dictionaries) sub values by a single string "..."
+    ///
+    /// - Important: To be used only for display purpose as the returned string will not have a proper format
     func exportFoldedString(upTo level: Int) throws -> String
 }
 
+extension SerializablePathExplorer {
+
+    var defaultCSVSeparator: String { ";" }
+    var nullCSVValue: String { "NULL" }
+}
+
 public extension SerializablePathExplorer {
 
-    var defaultCSVSeparator: String { ";" }
-    var nullCSVValue: String { "NULL" }
-
-    /// Export the path explorer value to a CSV if possible. Use the default separator ';' if none specified
+    /// Export the path explorer value to a CSV if possible. Using the default separator ';'
+    ///
+    /// - note: Not all values are exportable to CSV. For instance, a three dimensions array is not exportable, neither an array of heterogeneous dictionaries.
     func exportCSV() throws -> String {
         try exportCSV(separator: nil)
     }

Sources/Scout/Scout.docc/Articles/getting-started.md

@@ -33,15 +33,24 @@ Tom:
   - guitar
 ```
 
-## Navigate through data
+## Create a PathExplorer
 
-The simplest way to read data in any of the supported format is to use one of the ``PathExplorers`` implementation.
-For instance, let's imagine that the file is read and converted to a `Data` value. Here's how to make an explorer for the YAML format, using ``SerializablePathExplorer/init(data:)``
+The simplest way to read data in any of the supported format is to use one of the ``PathExplorers`` implementation and to call ``SerializablePathExplorer/init(data:)``.
+
+For instance, let's imagine that the file is read and converted to a `Data` value. Here's how to make an explorer for the YAML format.
 
 ```swift
 let yaml = try PathExplorers.Yaml(data: data)
 ```
 
+Similarly, if the format was Plist:
+
+```swift
+let plist = try PathExplorers.Plist(data: data)
+```
+
+## Navigate through data
+
 It's then possible to use the ``PathExplorer/get(_:)-2ghf1`` method to read the "height" value in the "Tom" dictionary.
 
 ```swift
@@ -62,10 +71,10 @@ let tomHeight = try yaml.get("Tom", "height").double
 
 > Note: As you might have noticed, calling `get()` can throw an error. This is the case for most `PathExplorer` functions. Whenever an element in the provided path does not exist, for instance an index out of bounds, or a missing key, a relevant error will be thrown to let you take the relevant action.
 
-As a last example, here's how to read Robert first hobby:
+As a last example, here's how to read Robert first hobby inside an array:
 
 ```swift
-let robert1stHobby = try yaml.get("Robert", "hobbies", 0)
+let robertFirstHobby = try yaml.get("Robert", "hobbies", 0)
 ```
 
 > Tip: Use negative indexes to specify an index from the *end* of the array.
@@ -108,3 +117,11 @@ let result = yaml
 
 ## Export the results
 
+If ``PathExplorer``  is used to navigate through data, the protocol ``SerializablePathExplorer`` refines it to offer import and export options.
+
+Once you are satisfied with the resulting `SerializablePathExplorer` - regardless of the operations you performed - it's possible to export the explorer as a `Data` value or to another format.
+To export it to a `Data` value, use ``SerializablePathExplorer/exportData()`` function.
+
+When needed, it's possible to specify another format when exporting: for instance, if a plist was decoded from a file and has to be converted to a JSON format. See ``SerializablePathExplorer/exportData(to:)`` for more informations.
+
+Similarly, other export features are available like export to a `String` or to a CSV string.

Sources/Scout/Scout.docc/Articles/mastering-paths.md

@@ -1,5 +1,5 @@
 # Mastering Paths
 
-``Path``s provided to a ``PathExplorer``to navigate or manipulate data precisely.
+``Path``s are provided to a ``PathExplorer`` to navigate through or manipulate data precisely.
 
 ## Overview

Sources/Scout/Scout.docc/Extensions/serializable-path-explorer-export-folder.md

@@ -0,0 +1,87 @@
+# ``Scout/SerializablePathExplorer/exportFoldedString(upTo:)``
+
+@Metadata {
+    @DocumentationExtension(mergeBehavior: append)
+}
+### Examples
+
+With the following JSON stored in a `SerializablePathExplorer` named `json`.
+
+```json
+{
+  "Tom" : {
+    "age" : 68,
+    "hobbies" : [
+      "cooking",
+      "guitar"
+    ],
+    "height" : 175
+  },
+  "Robert" : {
+    "age" : 23,
+    "hobbies" : [
+      "video games",
+      "party",
+      "tennis"
+    ],
+    "running_records" : [
+      [
+        10,
+        12,
+        9,
+        10
+      ],
+      [
+        9,
+        12,
+        11
+      ]
+    ],
+    "height" : 181
+  },
+  "Suzanne" : {
+    "job" : "actress",
+    "movies" : [
+      {
+        "title" : "Tomorrow is so far",
+        "awards" : "Best speech for a silent movie"
+      },
+      {
+        "title" : "Yesterday will never go",
+        "awards" : "Best title"
+      },
+      {
+        "title" : "What about today?"
+      }
+    ]
+  }
+}
+```
+
+The following
+
+```swift
+json.exportFoldedString(upTo: 2)
+```
+
+will return the string:
+
+```json
+{
+  "Suzanne" : {
+    "job" : "actress",
+    "movies" : [...]
+  },
+  "Tom" : {
+    "hobbies" : [...],
+    "age" : 68,
+    "height" : 175
+  },
+  "Robert" : {
+    "running_records" : [...],
+    "age" : 23,
+    "hobbies" : [...],
+    "height" : 181
+  }
+}
+```

Sources/Scout/Scout.docc/Extensions/serializable-path-explorer.md

@@ -6,10 +6,37 @@
 
 ## Overview
 
-Protocol refining ``PathExplorer`` to offer features like conversion to another format or serialization. Explorers in  ``PathExplorers`` implement this protocol.
+Protocol refining ``PathExplorer`` to offer features like conversion to another format or serialization. Explorers in ``PathExplorers`` implement this protocol.
 
 ## Topics
 
-### <!--@START_MENU_TOKEN@-->Group<!--@END_MENU_TOKEN@-->
+### Initializers
 
-- <!--@START_MENU_TOKEN@-->``Symbol``<!--@END_MENU_TOKEN@-->
+- ``init(data:)``
+- ``fromCSV(string:separator:hasHeaders:)``
+
+### Get format info
+
+- ``format``
+
+### Export as Data
+
+- ``exportData()``
+- ``exportData(to:)``
+- ``exportData(to:rootName:)``
+
+### Export as String
+
+- ``exportString()``
+- ``exportString(to:)``
+- ``exportString(to:rootName:)``
+
+### Export as CSV
+
+- ``exportCSV()``
+- ``exportCSV(separator:)``
+
+### Export folded String
+
+- ``exportFoldedString(upTo:)``
+- ``folded(upTo:)``