Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add markup delimiters supported by Xcode #654

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Add markup delimiters supported by Xcode #654

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fc8e67c
Add SwiftDoc keys for 'abstract' and supported delimiters
eneko May 29, 2020
435921a
Project file
eneko May 29, 2020
ed6a572
CHANGELOG
eneko May 30, 2020
33f32b2
Update Commandant fixtures for 5.1
eneko May 30, 2020
8cb0a61
Fixture updates
eneko May 30, 2020
84707b7
Merge remote-tracking branch 'upstream/master' into feature/markup-de…
eneko May 30, 2020
43b1fb0
Fixture updates from Xcode 10.3
eneko May 30, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@

* Update Yams to 3.0.0.
[Keith Smiley](https://github.com/keith)
* Extract all supported delimiters from document XML.
[Eneko Alonso](https://github.com/eneko)

##### Bug Fixes

Expand Down
32 changes: 32 additions & 0 deletions Source/SourceKittenFramework/File.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -459,6 +459,10 @@ public func parseFullXMLDocs(_ xmlDocs: String) -> [String: SourceKitRepresentab
.replacingOccurrences(of: "</rawHTML>", with: "")
.replacingOccurrences(of: "<codeVoice>", with: "`")
.replacingOccurrences(of: "</codeVoice>", with: "`")
.replacingOccurrences(of: "<emphasis>", with: "_")
.replacingOccurrences(of: "</emphasis>", with: "_")
// .replacingOccurrences(of: "<strong>", with: "**")
// .replacingOccurrences(of: "</strong>", with: "**")
Comment on lines +464 to +465
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commented out by mistake?

Copy link
Collaborator Author

@eneko eneko May 30, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't have tests, will probably remove from this PR, or add tests.

return SWXMLHash.parse(cleanXMLDocs).children.first.map { rootXML in
var docs = [String: SourceKitRepresentable]()
docs[SwiftDocKey.docType.rawValue] = rootXML.element?.name
Expand All @@ -484,12 +488,40 @@ public func parseFullXMLDocs(_ xmlDocs: String) -> [String: SourceKitRepresentab
}
docs[SwiftDocKey.docParameters.rawValue] = parameters.map(docParameters(from:)) as [SourceKitRepresentable]
}
docs[SwiftDocKey.docAbstract.rawValue] = commentPartsXML["Abstract"].childrenAsArray()
docs[SwiftDocKey.docDiscussion.rawValue] = commentPartsXML["Discussion"].childrenAsArray()
docs[SwiftDocKey.docResultDiscussion.rawValue] = commentPartsXML["ResultDiscussion"].childrenAsArray()
docs[SwiftDocKey.docThrowsDiscussion.rawValue] = commentPartsXML["ThrowsDiscussion"].childrenAsArray()
populateDelimiters(docs: &docs, discussion: commentPartsXML["Discussion"])
return docs
}
}

/// Delimiters extracted from discussion (supported by Xcode)
/// - see: https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/MarkupFunctionality.html
func populateDelimiters(docs: inout [String: SourceKitRepresentable], discussion: XMLIndexer) {
docs[SwiftDocKey.docAttention.rawValue] = discussion["Attention"].childrenAsArray()
docs[SwiftDocKey.docAuthor.rawValue] = discussion["Author"].childrenAsArray()
docs[SwiftDocKey.docAuthors.rawValue] = discussion["Authors"].childrenAsArray()
docs[SwiftDocKey.docBug.rawValue] = discussion["Bug"].childrenAsArray()
docs[SwiftDocKey.docComplexity.rawValue] = discussion["Complexity"].childrenAsArray()
docs[SwiftDocKey.docCopyright.rawValue] = discussion["Copyright"].childrenAsArray()
docs[SwiftDocKey.docDate.rawValue] = discussion["Date"].childrenAsArray()
docs[SwiftDocKey.docExperiment.rawValue] = discussion["Experiment"].childrenAsArray()
docs[SwiftDocKey.docImportant.rawValue] = discussion["Important"].childrenAsArray()
docs[SwiftDocKey.docInvariant.rawValue] = discussion["Invariant"].childrenAsArray()
docs[SwiftDocKey.docNote.rawValue] = discussion["Note"].childrenAsArray()
docs[SwiftDocKey.docPostcondition.rawValue] = discussion["Postcondition"].childrenAsArray()
docs[SwiftDocKey.docPrecondition.rawValue] = discussion["Precondition"].childrenAsArray()
docs[SwiftDocKey.docRemark.rawValue] = discussion["Remark"].childrenAsArray()
docs[SwiftDocKey.docRequires.rawValue] = discussion["Requires"].childrenAsArray()
docs[SwiftDocKey.docSeeAlso.rawValue] = discussion["See"].childrenAsArray()
docs[SwiftDocKey.docSince.rawValue] = discussion["Since"].childrenAsArray()
docs[SwiftDocKey.docToDo.rawValue] = discussion["TODO"].childrenAsArray()
docs[SwiftDocKey.docVersion.rawValue] = discussion["Version"].childrenAsArray()
docs[SwiftDocKey.docWarning.rawValue] = discussion["Warning"].childrenAsArray()
}

private extension XMLIndexer {
/**
Returns an `[SourceKitRepresentable]` of `[String: SourceKitRepresentable]` items from `indexer` children, if any.
Expand Down
47 changes: 47 additions & 0 deletions Source/SourceKittenFramework/SwiftDocKey.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ public enum SwiftDocKey: String {
case documentationComment = "key.doc.comment"
/// Declaration of documented token (String).
case docDeclaration = "key.doc.declaration"
/// Abstract of documented token
case docAbstract = "key.doc.abstract"
/// Discussion documentation of documented token ([SourceKitRepresentable]).
case docDiscussion = "key.doc.discussion"
/// File where the documented token is located (String).
Expand All @@ -65,6 +67,8 @@ public enum SwiftDocKey: String {
case docParameters = "key.doc.parameters"
/// Parsed declaration (String).
case docResultDiscussion = "key.doc.result_discussion"
/// Throws delimiter from documented token
case docThrowsDiscussion = "key.doc.throws_discussion"
/// Parsed scope start (Int64).
case docType = "key.doc.type"
/// Parsed scope start end (Int64).
Expand All @@ -90,6 +94,49 @@ public enum SwiftDocKey: String {
/// Annotations ([String]).
case annotations = "key.annotations"

// MARK: Delimiters extracted from discussion

/// Content of `- attention:` delimiter
case docAttention = "key.doc.attention"
/// Content of `- author:` delimiter
case docAuthor = "key.doc.author"
/// Content of `- authors:` delimiter
case docAuthors = "key.doc.authors"
/// Content of `- bug:` delimiter
case docBug = "key.doc.bug"
/// Content of `- complexity:` delimiter
case docComplexity = "key.doc.complexity"
/// Content of `- copyright:` delimiter
case docCopyright = "key.doc.copyright"
/// Content of `- date:` delimiter
case docDate = "key.doc.date"
/// Content of `- experiment:` delimiter
case docExperiment = "key.doc.experiment"
/// Content of `- important:` delimiter
case docImportant = "key.doc.important"
/// Content of `- invariant:` delimiter
case docInvariant = "key.doc.invariant"
/// Content of `- note:` delimiter
case docNote = "key.doc.note"
/// Content of `- postcondition:` delimiter
case docPostcondition = "key.doc.postcondition"
/// Content of `- precondition:` delimiter
case docPrecondition = "key.doc.precondition"
/// Content of `- remark:` delimiter
case docRemark = "key.doc.remark"
/// Content of `- requires:` delimiter
case docRequires = "key.doc.requires"
/// Content of `- see:` and `- seealso:` delimiters
case docSeeAlso = "key.doc.see_also"
/// Content of `- since:` delimiter
case docSince = "key.doc.since"
/// Content of `- toDo:` delimiter
case docToDo = "key.doc.to_do"
/// Content of `- version:` delimiter
case docVersion = "key.doc.version"
/// Content of `- warning:` delimiter
case docWarning = "key.doc.warning"

// MARK: Typed SwiftDocKey Getters

/**
Expand Down
60 changes: 60 additions & 0 deletions Tests/SourceKittenFrameworkTests/Fixtures/[email protected]
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,11 @@
],
"key.bodylength" : 2222,
"key.bodyoffset" : 248,
"key.doc.abstract" : [
{
"Para" : "🚲 A two-wheeled, human-powered mode of transportation."
}
],
"key.doc.column" : 14,
"key.doc.comment" : "🚲 A two-wheeled, human-powered mode of transportation.",
"key.doc.declaration" : "public class Bicycle",
Expand Down Expand Up @@ -88,6 +93,11 @@
],
"key.bodylength" : 49,
"key.bodyoffset" : 492,
"key.doc.abstract" : [
{
"Para" : "Frame and construction style."
}
],
"key.doc.column" : 17,
"key.doc.comment" : "Frame and construction style.\n\n- Road: For streets or trails.\n- Touring: For long journeys.\n- Cruiser: For casual trips around town.\n- Hybrid: For general-purpose transportation.",
"key.doc.declaration" : "public enum Bicycle.Bicycle.Style",
Expand Down Expand Up @@ -213,6 +223,11 @@
],
"key.bodylength" : 60,
"key.bodyoffset" : 733,
"key.doc.abstract" : [
{
"Para" : "Mechanism for converting pedal power into motion."
}
],
"key.doc.column" : 17,
"key.doc.comment" : "Mechanism for converting pedal power into motion.\n\n- Fixed: A single, fixed gear.\n- Freewheel: A variable-speed, disengageable gear.",
"key.doc.declaration" : "public enum Bicycle.Bicycle.Gearing",
Expand Down Expand Up @@ -304,6 +319,11 @@
"key.annotated_decl" : "<Declaration>enum <Type usr=\"s:7BicycleAAC\">Bicycle<\/Type>.Handlebar<\/Declaration>",
"key.bodylength" : 47,
"key.bodyoffset" : 1009,
"key.doc.abstract" : [
{
"Para" : "Hardware used for steering."
}
],
"key.doc.column" : 10,
"key.doc.comment" : "Hardware used for steering.\n\n- Riser: A casual handlebar.\n- Café: An upright handlebar.\n- Drop: A classic handlebar.\n- Bullhorn: A powerful handlebar.",
"key.doc.declaration" : "enum Bicycle.Bicycle.Handlebar",
Expand Down Expand Up @@ -420,6 +440,11 @@
{
"key.accessibility" : "source.lang.swift.accessibility.internal",
"key.annotated_decl" : "<Declaration>let style: <Type usr=\"s:7BicycleAAC5StyleO\">Style<\/Type><\/Declaration>",
"key.doc.abstract" : [
{
"Para" : "The style of the bicycle."
}
],
"key.doc.column" : 9,
"key.doc.comment" : "The style of the bicycle.",
"key.doc.declaration" : "let style: Style",
Expand Down Expand Up @@ -448,6 +473,11 @@
{
"key.accessibility" : "source.lang.swift.accessibility.internal",
"key.annotated_decl" : "<Declaration>let gearing: <Type usr=\"s:7BicycleAAC7GearingO\">Gearing<\/Type><\/Declaration>",
"key.doc.abstract" : [
{
"Para" : "The gearing of the bicycle."
}
],
"key.doc.column" : 9,
"key.doc.comment" : "The gearing of the bicycle.",
"key.doc.declaration" : "let gearing: Gearing",
Expand Down Expand Up @@ -476,6 +506,11 @@
{
"key.accessibility" : "source.lang.swift.accessibility.internal",
"key.annotated_decl" : "<Declaration>let handlebar: <Type usr=\"s:7BicycleAAC9HandlebarO\">Handlebar<\/Type><\/Declaration>",
"key.doc.abstract" : [
{
"Para" : "The handlebar of the bicycle."
}
],
"key.doc.column" : 9,
"key.doc.comment" : "The handlebar of the bicycle.",
"key.doc.declaration" : "let handlebar: Handlebar",
Expand Down Expand Up @@ -504,6 +539,11 @@
{
"key.accessibility" : "source.lang.swift.accessibility.internal",
"key.annotated_decl" : "<Declaration>let frameSize: <Type usr=\"s:Si\">Int<\/Type><\/Declaration>",
"key.doc.abstract" : [
{
"Para" : "The size of the frame, in centimeters."
}
],
"key.doc.column" : 9,
"key.doc.comment" : "The size of the frame, in centimeters.",
"key.doc.declaration" : "let frameSize: Int",
Expand Down Expand Up @@ -539,6 +579,11 @@
"key.offset" : 1374
}
],
"key.doc.abstract" : [
{
"Para" : "The number of trips travelled by the bicycle."
}
],
"key.doc.column" : 22,
"key.doc.comment" : "The number of trips travelled by the bicycle.",
"key.doc.declaration" : "private(set) var numberOfTrips: Int {\n get\n }",
Expand Down Expand Up @@ -575,6 +620,11 @@
"key.offset" : 1479
}
],
"key.doc.abstract" : [
{
"Para" : "The total distance travelled by the bicycle, in meters."
}
],
"key.doc.column" : 22,
"key.doc.comment" : "The total distance travelled by the bicycle, in meters.",
"key.doc.declaration" : "private(set) var distanceTravelled: Double {\n get\n }",
Expand Down Expand Up @@ -606,6 +656,11 @@
"key.annotated_decl" : "<Declaration>init(style: <Type usr=\"s:7BicycleAAC5StyleO\">Style<\/Type>, gearing: <Type usr=\"s:7BicycleAAC7GearingO\">Gearing<\/Type>, handlebar: <Type usr=\"s:7BicycleAAC9HandlebarO\">Handlebar<\/Type>, frameSize centimeters: <Type usr=\"s:Si\">Int<\/Type>)<\/Declaration>",
"key.bodylength" : 192,
"key.bodyoffset" : 2010,
"key.doc.abstract" : [
{
"Para" : "Initializes a new bicycle with the provided parts and specifications."
}
],
"key.doc.column" : 5,
"key.doc.comment" : "Initializes a new bicycle with the provided parts and specifications.\n\n- parameter style: The style of the bicycle\n- parameter gearing: The gearing of the bicycle\n- parameter handlebar: The handlebar of the bicycle\n- parameter centimeters: The frame size of the bicycle, in centimeters\n\n- returns: A beautiful, brand-new, custom built just for you.",
"key.doc.declaration" : "init(style: Style, gearing: Gearing, handlebar: Handlebar, frameSize centimeters: Int)",
Expand Down Expand Up @@ -678,6 +733,11 @@
"key.annotated_decl" : "<Declaration>func travel(distance meters: <Type usr=\"s:Sd\">Double<\/Type>)<\/Declaration>",
"key.bodylength" : 112,
"key.bodyoffset" : 2356,
"key.doc.abstract" : [
{
"Para" : "Take a bike out for a spin."
}
],
"key.doc.column" : 10,
"key.doc.comment" : "Take a bike out for a spin.\n\n- parameter meters: The distance to travel in meters.",
"key.doc.declaration" : "func travel(distance meters: Double)",
Expand Down
Loading