swift-doc

swift-doc copied to clipboard

Feature request: source tags and source links

It is possible to add source tags (e.g. Tag: Some.Tag.Name) and source links (e.g. [description](x-source-tag://Some.Tag.Name)) to Swift documentation, and Xcode is able to parse this and provide links in rendered documentation.

It would be good if swift-doc's documentation generation would also be able to handle these source tags and source links and render these as HTML anchors (in case the output is set to HTML).

It might be a bit challenging to properly parse this into anchors, so perhaps a naming convention might be necessary.

Source tag

The source tag can be linked to.

/// Some example method.
///
/// Some elaborate description of what this method does.
/// 
/// - Tag: Foo.Bar.someMethod
func someMethod() { ... }

Source link

Another piece of documentation can have a source-link defined to quickly jump to other parts of the documentation.

/// ...
/// Please refer to [someMethod](x-source-tag://Foo.Bar.someMethod) for more information.
/// ...