Skip to content
This repository has been archived by the owner on Oct 17, 2021. It is now read-only.
/ SwiftMarkup Public archive

Parses Swift documentation comments into structured entities

License

Notifications You must be signed in to change notification settings

SwiftDocOrg/SwiftMarkup

Repository files navigation

SwiftMarkup

CI Documentation

SwiftMarkup parses Swift Markup from documentation comments into structured documentation entities.

import SwiftMarkup

let markdown = #"""
Creates a new bicycle with the provided parts and specifications.

- Remark: Satisfaction guaranteed!

The word *bicycle* first appeared in English print in 1868
to describe "Bysicles and trysicles" on the
"Champs Elysées and Bois de Boulogne".

- Parameters:
   - style: The style of the bicycle
   - gearing: The gearing of the bicycle
   - handlebar: The handlebar of the bicycle
   - frameSize: The frame size of the bicycle, in centimeters

- Returns: A beautiful, brand-new bicycle,
           custom-built just for you.
"""#
let documentation = try Documentation.parse(markdown)

documentation.summary?.description // "Creates a new bicycle with the provided parts and specifications."

documentation.discussionParts.count // 2

if case .callout(let remark) = documentation.discussionParts[0] {
    _ = remark.content // "Satisfaction guaranteed\\!"
}

if case .paragraph(let paragraph) = documentation.discussionParts[1] {
    _ = paragraph.description // "The word *bicycle* first appeared in English print in 1868 [ ... ]"
}

documentation.parameters[0].name // "style"
documentation.parameters[0]?.content.description // "The style of the bicycle"

documentation.returns?.description // A beautiful, brand-new bicycle, custom-built just for you.

This package is used by swift-doc in coordination with CommonMark and SwiftSemantics to generate documentation for Swift projects.

Requirements

  • Swift 5.2+

Installation

Swift Package Manager

Add the SwiftMarkup package to your target dependencies in Package.swift:

import PackageDescription

let package = Package(
  name: "YourProject",
  dependencies: [
    .package(
        url: "https://github.com/SwiftDocOrg/SwiftMarkup",
        from: "0.3.0"
    ),
  ]
)

Then run the swift build command to build your project.

License

MIT

Contact

Mattt (@mattt)