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

Update LinkDestinationSummary to support multi-language content #54

Merged
merged 12 commits into from
Dec 16, 2021
Merged

Update LinkDestinationSummary to support multi-language content #54

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0eafe44
Move content into a source language variant structure
d-ronnqvist Dec 1, 2021
93dbb4d
Update LinkDestinationSummary to match spec changes
d-ronnqvist Dec 3, 2021
76dd568
Merge branch 'main' into multi-languge-linkable-entities-spec
d-ronnqvist Dec 9, 2021
b729677
Merge branch 'main' into multi-languge-linkable-entities-spec
d-ronnqvist Dec 10, 2021
145343f
Merge branch 'main' into multi-languge-linkable-entities-spec
d-ronnqvist Dec 13, 2021
e6196d9
Move `usr` out of variant substructure since it doesn't vary
d-ronnqvist Dec 13, 2021
2cc7169
Update the spec to reduce the amount of duplicate data.
d-ronnqvist Dec 14, 2021
347dd84
Merge branch 'multi-languge-linkable-entities-spec' of github.com:d-r…
d-ronnqvist Dec 14, 2021
c68d31a
Remove extra closing back-tick in documentation comments
d-ronnqvist Dec 14, 2021
afaa56e
Use an alias to make optionality of variant properties more explicit
d-ronnqvist Dec 15, 2021
461d404
Remove trait from main summary element to avoid using it as a languag…
d-ronnqvist Dec 16, 2021
3994142
Small documentation comment refinements
d-ronnqvist Dec 16, 2021
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
167 changes: 142 additions & 25 deletions Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,15 @@ import SymbolKit
/// - In a paragraph of text, a link to this element will use the ``title`` as the link text and style the tile in code font if the ``kind`` is a type of symbol.
/// - In a task group, the the ``title`` and ``abstract-swift.property`` is displayed together to give more context about this element and the element may be marked as deprecated
/// based on the values of its ``platforms`` and other metadata about the current versions of the platforms.
///
/// The summary may include content that vary based on the source language. The content that is different in another source language is specified in a ``Variant``. Any property on the variant that is `nil` has the same value as the summarized element's value.
public struct LinkDestinationSummary: Codable, Equatable {
/// The traits of the summarized element.
let traits: [RenderNode.Variant.Trait]

/// The kind of the summarized element.
public let kind: DocumentationNode.Kind

/// The language of the summarized element.
public let language: SourceLanguage

/// The relative path to this element.
public let path: String

Expand Down Expand Up @@ -142,6 +144,51 @@ public struct LinkDestinationSummary: Codable, Equatable {
///
/// A web server can use this list of URLs to redirect to the current URL.
public let redirects: [URL]?

/// A variant of content for a summarized element.
///
/// - Note: All properties except for ``traits`` are optional. If a property is `nil` it means that the value is the same as the summarized element's value.
public struct Variant: Codable, Equatable {
/// The traits of the variant.
public let traits: [RenderNode.Variant.Trait]

/// A wrapper for variant values that are either set (the variant has a custom value) not set (the variant have the same value as the summarized element)
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
/// A wrapper for variant values that are either set (the variant has a custom value) not set (the variant have the same value as the summarized element)
/// A wrapper for variant values that can either be specified, meaning the variant has a custom value, or not, meaning the variant has the same value as the summarized element.

///
/// This alias is used to make the property declarations more explicit while at the same time offering the convenient syntax of optionals.
public typealias VariantValue = Optional

/// The kind of the variant or `nil` if the kind is the same as the summarized element.
Copy link
Contributor

Choose a reason for hiding this comment

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

Should we use .none here maybe? To differentiate between the wrapper and the inner value a little more.

Suggested change
/// The kind of the variant or `nil` if the kind is the same as the summarized element.
/// The kind of the variant or `.none` if the kind is the same as the summarized element.

public let kind: VariantValue<DocumentationNode.Kind>

/// The relative path of the variant or `nil` if the relative is the same as the summarized element.
public let path: VariantValue<String>

/// The title of the variant or `nil` if the title is the same as the summarized element.
public let title: VariantValue<String?>

/// The abstract of the variant or `nil` if the abstract is the same as the summarized element.
///
/// - Note: If the summarized element has an abstract but the variant doesn't, this property will be `Optional.some(nil)`.
Copy link
Contributor

Choose a reason for hiding this comment

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

Nit: Note's render kind of strangely if they're not embedded in other content. It might be better to just make this a regular discussion.

Suggested change
/// - Note: If the summarized element has an abstract but the variant doesn't, this property will be `Optional.some(nil)`.
/// If the summarized element has an abstract but the variant doesn't, this property will be `Optional.some(nil)`.

public let abstract: VariantValue<Abstract?>

/// The taskGroups of the variant or `nil` if the taskGroups is the same as the summarized element.
///
/// - Note: If the summarized element has task groups but the variant doesn't, this property will be `Optional.some(nil)`.
public let taskGroups: VariantValue<[TaskGroup]?>

/// The precise symbol identifier of the variant or `nil` if the precise symbol identifier is the same as the summarized element.
///
/// - Note: If the summarized element has a precise symbol identifier but the variant doesn't, this property will be `Optional.some(nil)`.
public let usr: VariantValue<String?>

/// The declaration of the variant or `nil` if the declaration is the same as the summarized element.
///
/// - Note: If the summarized element has a declaration but the variant doesn't, this property will be `Optional.some(nil)`.
public let declarationFragments: VariantValue<DeclarationFragments?>
}

/// The variants of content (kind, title, abstract, path, urs, declaration, and task groups) for this summarized element.
public let variants: [Variant]
}

// MARK: - Accessing the externally linkable elements
Expand Down Expand Up @@ -205,25 +252,22 @@ extension LinkDestinationSummary {
/// - taskGroups: The task groups that lists the children of this page.
/// - compiler: The content compiler that's used to render the node's abstract.
init(documentationNode: DocumentationNode, path: String, taskGroups: [TaskGroup], platforms: [PlatformAvailability]?, compiler: inout RenderContentCompiler) {
let declaration = (documentationNode.semantic as? Symbol)?.subHeading.map { declaration in
return declaration.map { fragment in
DeclarationRenderSection.Token(fragment: fragment, identifier: nil)
}
}

let symbol = documentationNode.semantic as? Symbol

self.init(
traits: [.interfaceLanguage(documentationNode.sourceLanguage.id)],
kind: documentationNode.kind,
language: documentationNode.sourceLanguage,
path: path,
referenceURL: documentationNode.reference.url,
title: ReferenceResolver.title(forNode: documentationNode),
abstract: (documentationNode.semantic as? Abstracted)?.renderedAbstract(using: &compiler),
availableLanguages: documentationNode.availableSourceLanguages,
platforms: platforms,
taskGroups: taskGroups,
usr: (documentationNode.semantic as? Symbol)?.externalID,
declarationFragments: declaration,
redirects: (documentationNode.semantic as? Redirected)?.redirects?.map { $0.oldPath }
usr: symbol?.externalID,
declarationFragments: symbol?.subHeading?.map { .init(fragment: $0, identifier: nil) },
redirects: (documentationNode.semantic as? Redirected)?.redirects?.map { $0.oldPath },
variants: []
)
}
}
Expand All @@ -240,18 +284,18 @@ extension LinkDestinationSummary {
init(landmark: Landmark, basePath: String, page: DocumentationNode, platforms: [PlatformAvailability]?, compiler: inout RenderContentCompiler) {
let anchor = urlReadableFragment(landmark.title)

let abstract: Abstract
let abstract: Abstract?
if let abstracted = landmark as? Abstracted {
abstract = abstracted.renderedAbstract(using: &compiler) ?? []
} else if let paragraph = landmark.markup.children.lazy.compactMap({ $0 as? Paragraph }).first, case RenderBlockContent.paragraph(let inlineContent)? = compiler.visitParagraph(paragraph).first {
abstract = inlineContent
} else {
abstract = []
abstract = nil
}

self.init(
traits: [.interfaceLanguage(page.sourceLanguage.id)],
kind: .onPageLandmark,
language: page.sourceLanguage,
path: basePath + "#\(anchor)", // use an in-page anchor for the landmark's path
referenceURL: page.reference.withFragment(anchor).url,
title: landmark.title,
Expand All @@ -261,7 +305,8 @@ extension LinkDestinationSummary {
taskGroups: [], // Landmarks have no children
usr: nil, // Only symbols have a USR
declarationFragments: nil, // Only symbols have declarations
redirects: (landmark as? Redirected)?.redirects?.map { $0.oldPath }
redirects: (landmark as? Redirected)?.redirects?.map { $0.oldPath },
variants: []
)
}
}
Expand All @@ -271,24 +316,31 @@ extension LinkDestinationSummary {
// Add Codable methods—which include an initializer—in an extension so that it doesn't override the member-wise initializer.
extension LinkDestinationSummary {
enum CodingKeys: String, CodingKey {
case kind, path, referenceURL, title, abstract, language, taskGroups, usr, availableLanguages, platforms, redirects
case traits, kind, path, referenceURL, title, abstract, taskGroups, usr, availableLanguages, platforms, redirects, variants
case declarationFragments = "fragments"
}

enum LegacyCodingKeys: String, CodingKey {
case language
}

public func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encode(traits, forKey: .traits)
try container.encode(referenceURL, forKey: .referenceURL)
try container.encode(kind.id, forKey: .kind)
try container.encode(path, forKey: .path)
try container.encode(referenceURL, forKey: .referenceURL)
try container.encode(title, forKey: .title)
try container.encodeIfPresent(abstract, forKey: .abstract)
try container.encode(language.id, forKey: .language)
try container.encode(availableLanguages.map { $0.id }, forKey: .availableLanguages)
try container.encodeIfPresent(platforms, forKey: .platforms)
try container.encodeIfPresent(taskGroups, forKey: .taskGroups)
try container.encodeIfPresent(usr, forKey: .usr)
try container.encodeIfPresent(declarationFragments, forKey: .declarationFragments)
try container.encodeIfPresent(redirects, forKey: .redirects)
if !variants.isEmpty {
try container.encode(variants, forKey: .variants)
}
}

public init(from decoder: Decoder) throws {
Expand All @@ -302,11 +354,6 @@ extension LinkDestinationSummary {
referenceURL = try container.decode(URL.self, forKey: .referenceURL)
title = try container.decode(String.self, forKey: .title)
abstract = try container.decodeIfPresent(Abstract.self, forKey: .abstract)
let languageID = try container.decode(String.self, forKey: .language)
guard let foundLanguage = SourceLanguage.knownLanguages.first(where: { $0.id == languageID }) else {
throw DecodingError.dataCorruptedError(forKey: .language, in: container, debugDescription: "Unknown SourceLanguage identifier: '\(languageID)'.")
}
language = foundLanguage

let availableLanguageIDs = try container.decode([String].self, forKey: .availableLanguages)
availableLanguages = try Set(availableLanguageIDs.map { languageID in
Expand All @@ -320,5 +367,75 @@ extension LinkDestinationSummary {
usr = try container.decodeIfPresent(String.self, forKey: .usr)
declarationFragments = try container.decodeIfPresent(DeclarationFragments.self, forKey: .declarationFragments)
redirects = try container.decodeIfPresent([URL].self, forKey: .redirects)

variants = try container.decodeIfPresent([Variant].self, forKey: .variants) ?? []
do {
let traits = try container.decode([RenderNode.Variant.Trait].self, forKey: .traits)
for case .interfaceLanguage(let languageID) in traits {
guard SourceLanguage.knownLanguages.contains(where: { $0.id == languageID }) else {
throw DecodingError.dataCorruptedError(forKey: .traits, in: container, debugDescription: "Unknown SourceLanguage identifier: '\(languageID)'.")
}
}
self.traits = traits
} catch DecodingError.keyNotFound(_, let originalErrorContext) {
Copy link
Contributor

Choose a reason for hiding this comment

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

Should we do a version check instead (== "0.1.0") for the legacy decoding rather than falling back to it if the variants key is missing, or do you think it's not worth it?

Copy link
Contributor Author

@d-ronnqvist d-ronnqvist Dec 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

That would require that we encode the version information in the JSON, which we would probably do once for the entire file instead of once for per element.

// Attempts to decode the legacy format and raise the original keyNotFound if that doesn't work.
do {
let legacyContainer = try decoder.container(keyedBy: LegacyCodingKeys.self)

let languageID = try legacyContainer.decode(String.self, forKey: .language)
guard SourceLanguage.knownLanguages.contains(where: { $0.id == languageID }) else {
throw DecodingError.dataCorruptedError(forKey: .language, in: legacyContainer, debugDescription: "Unknown SourceLanguage identifier: '\(languageID)'.")
}
traits = [.interfaceLanguage(languageID)]
} catch {
throw DecodingError.keyNotFound(CodingKeys.traits, originalErrorContext)
}
}
}
}

extension LinkDestinationSummary.Variant {
enum CodingKeys: String, CodingKey {
case traits, kind, path, title, abstract, usr, declarationFragments = "fragments", taskGroups
}

public func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encode(traits, forKey: .traits)
try container.encodeIfPresent(kind?.id, forKey: .kind)
try container.encodeIfPresent(path, forKey: .path)
try container.encodeIfPresent(title, forKey: .title)
try container.encodeIfPresent(abstract, forKey: .abstract)
try container.encodeIfPresent(usr, forKey: .usr)
try container.encodeIfPresent(declarationFragments, forKey: .declarationFragments)
try container.encodeIfPresent(taskGroups, forKey: .taskGroups)
}

public init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)

let traits = try container.decode([RenderNode.Variant.Trait].self, forKey: .traits)
for case .interfaceLanguage(let languageID) in traits {
guard SourceLanguage.knownLanguages.contains(where: { $0.id == languageID }) else {
throw DecodingError.dataCorruptedError(forKey: .traits, in: container, debugDescription: "Unknown SourceLanguage identifier: '\(languageID)'.")
}
}
self.traits = traits

let kindID = try container.decodeIfPresent(String.self, forKey: .kind)
if let kindID = kindID {
guard let foundKind = DocumentationNode.Kind.allKnownValues.first(where: { $0.id == kindID }) else {
throw DecodingError.dataCorruptedError(forKey: .kind, in: container, debugDescription: "Unknown DocumentationNode.Kind identifier: '\(kindID)'.")
}
kind = foundKind
} else {
kind = nil
}
path = try container.decodeIfPresent(String.self, forKey: .path)
title = try container.decodeIfPresent(String?.self, forKey: .title)
abstract = try container.decodeIfPresent(LinkDestinationSummary.Abstract?.self, forKey: .abstract)
usr = try container.decodeIfPresent(String?.self, forKey: .title)
declarationFragments = try container.decodeIfPresent(LinkDestinationSummary.DeclarationFragments?.self, forKey: .declarationFragments)
taskGroups = try container.decodeIfPresent([LinkDestinationSummary.TaskGroup]?.self, forKey: .taskGroups)
}
}
79 changes: 75 additions & 4 deletions Sources/SwiftDocC/SwiftDocC.docc/Resources/LinkableEntities.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"openapi": "3.0.0",
"info": {
"description": "Specification of the DocC linkable-entities.json digest file.",
"version": "0.1.0",
"version": "0.2.0",
"title": "Linkable Entities"
},
"paths": { },
Expand All @@ -18,7 +18,7 @@
"type": "object",
"required": [
"kind",
"language",
"traits",
"path",
"referenceURL",
"title",
Expand All @@ -28,8 +28,11 @@
"kind": {
"type": "string"
},
"language": {
"type": "string"
"traits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RenderNodeVariantTrait"
}
},
"path": {
"type": "string"
Expand Down Expand Up @@ -78,6 +81,12 @@
"items": {
"type": "string"
}
},
"variants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LinkDestinationSummaryVariant"
}
}
}
},
Expand All @@ -96,6 +105,68 @@
}
}
},
"RenderNodeVariantTrait": {
"oneOf": [
{
"$ref": "#/components/schemas/TraitInterfaceLanguage"
}
]
},
"TraitInterfaceLanguage": {
"required": [
"interfaceLanguage"
],
"type": "object",
"properties": {
"interfaceLanguage": {
"type": "string"
}
}
},
"LinkDestinationSummaryVariant": {
"type": "object",
"required": [
"traits",
],
"properties": {
"traits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RenderNodeVariantTrait"
}
},
"kind": {
"type": "string"
},
"path": {
"type": "string"
},
"title": {
"type": "string"
},
"abstract": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RenderInlineContent"
}
},
"usr": {
"type": "string"
},
"declarationFragments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DeclarationToken"
}
},
"taskGroups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskGroup"
}
}
}
},
"RenderInlineContent": {
"oneOf": [
{
Expand Down
Loading