I have a few sections in my content where I have a repeated example that I use to illustrate how to use a few methods in my library together - is there a way to move this into an external snippet and include it inline within existing content?
DocC supports standard Markdown code voice (``) and fenced code blocks (```...```). Please submit feedback with a description of your use case on the Feedback Assistant website.
To avoid having to copy and paste the same snippet in multiple places, though, one workaround is to place your snippet in the doc comments of one type, and then use DocC's link support to link from multiple comments to the type containing your snippet.
/// This is my function.
///
/// Typical usage of this function looks like this:
///
/// ```
/// ...illustrative snippet
/// ```
func myFunc() { /*...*/ }
/// This is another function.
///
/// This is typically used with ``myFunc()``.
func anotherFunc() { /*...*/ }
The double backticks around the text "myFunc()" in the second doc comment will become a link back to myFunc, providing readers an easy way to navigate to the docs that contain the snippet.
It would be great if we could reference code snippets in unit tests that are known to work and compile.
Having sample code that doesn't actually compile is a very common - and avoidable - problem.
Case in point: The code found here: https://developer.apple.com/documentation/authenticationservices/public-private_key_authentication/supporting_passkeys doesn't actually compile because the API has changed.
let platformProvider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: "example.com")
...should be...
let platformProvider = ASAuthorizationPlatformPublicKeyCredentialProvider("example.com")
Other platforms such as .NET's SandCastle Help File Builder support this capability, btw.
There was a pitch recently in on the Swift Evolution open source forums by Ashley Garland that related to this kind of setup - the idea being the documentation catalog could contain a specific set of swift snippets, and the compiler (or SwiftPM in this case I think) could/would build those to verify that everything kept working, no warnings, etc.
I don't know the current state of that pitch, but I think it's nearly exactly what you're after here.
(and I'm doing the same right now - including snippets in two places, one in my tests, and another in the doc comments)
DocC supports standard Markdown code voice (``) and fenced code blocks (```...```). Please submit feedback with a description of your use case on the Feedback Assistant website.
To avoid having to copy and paste the same snippet in multiple places, though, one workaround is to place your snippet in the doc comments of one type, and then use DocC's link support to link from multiple comments to the type containing your snippet.
/// This is my function.
///
/// Typical usage of this function looks like this:
///
/// ```
/// ...illustrative snippet
/// ```
func myFunc() { /*...*/ }
/// This is another function.
///
/// This is typically used with ``myFunc()``.
func anotherFunc() { /*...*/ }
The double backticks around the text "myFunc()" in the second doc comment will become a link back to myFunc, providing readers an easy way to navigate to the docs that contain the snippet.
It would be great if we could reference code snippets in unit tests that are known to work and compile.
Having sample code that doesn't actually compile is a very common - and avoidable - problem.
Case in point: The code found here: https://developer.apple.com/documentation/authenticationservices/public-private_key_authentication/supporting_passkeys doesn't actually compile because the API has changed.
let platformProvider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: "example.com")
...should be...
let platformProvider = ASAuthorizationPlatformPublicKeyCredentialProvider("example.com")
Other platforms such as .NET's SandCastle Help File Builder support this capability, btw.
There was a pitch recently in on the Swift Evolution open source forums by Ashley Garland that related to this kind of setup - the idea being the documentation catalog could contain a specific set of swift snippets, and the compiler (or SwiftPM in this case I think) could/would build those to verify that everything kept working, no warnings, etc.
I don't know the current state of that pitch, but I think it's nearly exactly what you're after here.
(and I'm doing the same right now - including snippets in two places, one in my tests, and another in the doc comments)
It would be great if we could reference code snippets in unit tests that are known to work and compile.
Agreed. Speaking personally, I would love to have that feature. I encourage you to file an enhancement request along those lines. Please post your bug number, just for the record.
Also, in the 5 months since this thread was created DocC has be released as an open source project. I’m not involved in the open source effort but I’m pretty sure the folks over there would welcome your participation (-:
Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"
For code snippets in particular, there was a pitch recently in on the Swift Evolution open source forums by Ashley Garland that related to this — the idea being the documentation catalog could contain a specific set of swift snippets, and the compiler (or SwiftPM in this case I think) could/would build those to verify that everything kept working, no warnings, etc.
The snippets I want to include are more than just code snippets - I wanted to have the same content in multiple locations - akin to an "include this markdown file here" sort of marker, which I can do in other documentation systems to re-use some short content in multiple locations.
I submitted this as feedback: FB9779628, and now that DocC is open source, I'll look into the avenue of how I might enable this myself.
While I’m writing my documentation, I’d like to reference the same content - which includes a code snippet blocked out using the triple-backtick syntax as well as narrative content in regular markdown - in multiple locations within my docs.
Right now I have to copy/paste this bit into multiple areas, but I’d really prefer to have a means to “import/include” a stand-alone markdown file, that isn’t otherwise rendered into the documentation, so that I can keep a single location up to date with my code.