An Entity to extract Swift documentation comment.
Just add to your Package.swift under dependencies
let package = Package(
name: "MyPackage",
products: [...],
targets: [
.target(
"YouAppModule",
dependencies: [
.product(name: "DocumentationComment", package: "DocumentationComment")
]
)
],
dependencies: [
.package(url: "https://github.com/fumito-ito/DocumentationComment.git", .upToNextMajor(from: "0.0.2"))
]
)You can generate a DocumentationComment object by passing Swift's Annotation Comment as a string.
let annotationComment = """
/// Returns a command that runs unconditionally before every build.
///
/// Prebuild commands can have a significant performance impact
/// and should only be used when there would be no way to know the
/// list of output file paths without first reading the contents
/// of one or more input files. Typically there is no way to
/// determine this list without first running the command, so
/// instead of encoding that list, the caller supplies an
/// `outputFilesDirectory` parameter, and all files in that
/// directory after the command runs are treated as output files.
///
/// ```
/// let sampleText = "This is sample text"
/// ```
///
/// > the paths in the list of output files may depend on the list
/// > of input file paths, but **must not** depend on reading the contents
/// > of any input files. Such cases must be handled using a `prebuildCommand`.
///
/// - Parameters:
/// - executable: The absolute path to the executable to be invoked.
/// - arguments: Command-line arguments to be passed to the executable.
/// - Throws: Any error thrown by `deferred` or `work` (in that order).
/// - Returns: `true` if a path from `source` to `destination` exists, `false` otherwise.
/// - Attention: Special attention is needed for this part.
/// - Author: Who is the original author of this code?
"""
let doc = try DocumentationComment(annotationComment)DocumentationComment extracts a summary, arguments, etc. from the comment.
print(doc.abstract?.stringify) // => Returns a command that runs unconditionally before every build.
print(doc.parameters.first?.name) // => executable
print(doc.parameters.first?.description) // => The absolute path to the executable to be invoked.Block Comment format comments can also be handled.
let blockComment = """
/*
Returns a command that runs unconditionally before every build.
Prebuild commands can have a significant performance impact
and should only be used when there would be no way to know the
list of output file paths without first reading the contents
of one or more input files. Typically there is no way to
determine this list without first running the command, so
instead of encoding that list, the caller supplies an
`outputFilesDirectory` parameter, and all files in that
directory after the command runs are treated as output files.
\```
let sampleText = "This is sample text"
\```
> the paths in the list of output files may depend on the list
> of input file paths, but **must not** depend on reading the contents
> of any input files. Such cases must be handled using a `prebuildCommand`.
- Parameters:
- executable: The absolute path to the executable to be invoked.
- arguments: Command-line arguments to be passed to the executable.
- Throws: Any error thrown by `deferred` or `work` (in that order).
- Returns: `true` if a path from `source` to `destination` exists, `false` otherwise.
- Attention: Special attention is needed for this part.
- Author: Who is the original author of this code?
*/
"""
let doc = try DocumentationComment(blockComment)Extract the string corresponding to the first paragraph of the comment as a summary of that comment.
Extracts the second and subsequent paragraphs as comment details.
Extract parameter names and their details from the Parameters section or Parameter field.
- Parameters:
- x: ...
- y: ...
- z: ...- Parameter x: ...
- Parameter y: ...Extract its details from the Throws field.
- Throws: ...Extract its details from the Returns field.
- Returns: ...Extract its name and details from the Field Extensions field highlighted in Xcode's QuickHelp.
- Attention: ...
- Author: ...
- Authors: ...
- Bug: ...
- Complexity: ...
- Copyright: ...
- Date: ...
- Experiment: ...
- Important: ...
- Invariant: ...
- Note: ...
- Postcondition: ...
- Precondition: ...
- Remark: ...
- Remarks: ...
- Requires: ...
- See: ...
- Since: ...
- Todo: ...
- Version: ...
- Warning: ...