Split "filters" files #36
Conversation
…t only the platform version), so remove the version
There was a problem hiding this comment.
Nice! I'm assuming there were no code changes beyond the error types.
Just noticed a couple of typos + some inconsistencies in the doc blocks. In some blocks this isn't done:
- Parameters:
- in: ...
Note: I can do these tomorrow, right now I'm too tired from the return trip from the weekend.
Sources/Parameters.swift
Outdated
| typealias Parameter = (key: String, value: Any) | ||
| public typealias StringDict = [String: Any] | ||
|
|
||
| /// Transforms a list of strings representing structred-key/value pairs, like |
Sources/Parameters.swift
Outdated
| typealias Parameter = (key: String, value: Any) | ||
| public typealias StringDict = [String: Any] | ||
|
|
||
| /// Transforms a list of strings representing structred-key/value pairs, like | ||
| /// `["pt.x=1", "pt.y=2", "values=1", "values=2", "values=3" "flag"]` |
Sources/Parameters.swift
Outdated
| /// `["pt.x=1", "pt.y=2", "values=1", "values=2", "values=3" "flag"]` | ||
| /// into a structured dictionary. | ||
| /// | ||
| /// - Parameter items: The list of `k=v`-style Strings, each string |
There was a problem hiding this comment.
Shouldn't we use the same structure as in the other doc. blocks? Namely a - Paramters:, then newline, then a list of parameters (here - items:).
There was a problem hiding this comment.
Well when you ask Xcode to generate the doc comment (menu "Editor" > "Structure" > "Add Documentation"), it uses the "- Parameters + one param per line" if there's more than one parameter, but uses directly - Parameter foo if there's only one parameter.
I agree that's inconsistent, and I actually wondered the same as you here. idk if it's better to force consistency ourselves, using - Parameters + one param per line, or to just do as Xcode does (which at least would not force us to fight Xcode and correct every new contributor who are using Xcode's doc auto-generation shortcut)
There was a problem hiding this comment.
Hmm, leave it then. (I didn't even know that functionality existed).
There was a problem hiding this comment.
@djbe Approved for merge, then?
Sources/Parameters.swift
Outdated
| /// an existing StringDict dictionary being built. | ||
| /// | ||
| /// - Parameters: | ||
| /// - parameter: The parameter/string (key/Value pair) to parse |
Sources/Parameters.swift
Outdated
| /// - Parameters: | ||
| /// - parameter: The parameter/string (key/Value pair) to parse | ||
| /// - result: The dictionary currently being built and to which to add the value | ||
| /// - Returns: The new content of the dictionary being built after nserting the new parsed value |
|
|
||
| /// Checks if the string is one of the reserved keywords and if so, escapes it using backticks | ||
| /// | ||
| /// - Parameter in: the string to possibly escape |
There was a problem hiding this comment.
Use same structure as other doc blocks:
- Parameters:
- in: ...
|
|
||
| /// This returns the snake cased variant of the string. | ||
| /// | ||
| /// - Parameter string: The string to snake_case |
There was a problem hiding this comment.
See comments below related to doc block structure.
Sources/Filters+Strings.swift
Outdated
|
|
||
| /// This returns the string with its first parameter uppercased. | ||
| /// - note: This is quite similar to `capitalise` except that this filter doesn't | ||
| /// lowercase the rest of the string but keep it untouched. |
Old names for those types still exists as typealiases but marked as deprecated and will be removed by Remove deprecated, non nested error types #37