What's the pattern to provide organization around properties and methods within a struct or class?

Question

I'm using DocC to add documentation to an existing swift package, and the basics are working great - properties and methods showing up, linked pages, all the stuff you'd hope for.

I'd like to update the structure within the struct (or class) to organize the methods and properties a bit more akin to how Apple does it in their documentation - not just the default headers, but organized by why you'd use them.

Can this be done in DocC using headings within the doc comments in the source file directly, or do we need to add an Extension file with the same symbol name at the top to override and provide that additional structure?

The extension template looks like it might be redundant with the summary and overview sections, since that same area is (I think) what comes from the doc comments in the source headers.

# ``Symbol``

Summary

## Overview

Text

## Topics

### Group

- ``Symbol``

DocC

881

Posted by

heckj

Reply

Add a Comment

Answer 1

Answering my own question - it's in the documentation, I just missed it earlier. Yes - use the Extension file mechanism, as described in the section Arrange Nested Symbols in Extension Files of the article Adding Structure to your Documentation Pages.

I'm presuming that as you get multiple of these, a good practice would be consistent naming based on the symbol to which they're providing the organization. That's my own observation and not advised in the article.

The key to not repeating details of the symbol (the overview, etc) is with the following metadata code:

@Metadata {
    @DocumentationExtension(mergeBehavior: append)
}

Posted by

heckj

UPDATE: I had trouble getting the structure to reflect when I posted it inside the struct's source comments, but that does work, and an extension file isn't required.

—
heckj

Add a Comment

Answer 2

Answering my own question - it's in the documentation, I just missed it earlier. Yes - use the Extension file mechanism, as described in the section Arrange Nested Symbols in Extension Files of the article Adding Structure to your Documentation Pages.

I'm presuming that as you get multiple of these, a good practice would be consistent naming based on the symbol to which they're providing the organization. That's my own observation and not advised in the article.

The key to not repeating details of the symbol (the overview, etc) is with the following metadata code:

@Metadata {
    @DocumentationExtension(mergeBehavior: append)
}

Posted by

heckj

UPDATE: I had trouble getting the structure to reflect when I posted it inside the struct's source comments, but that does work, and an extension file isn't required.

—
heckj

Add a Comment

What's the pattern to provide organization around properties and methods within a struct or class?

Accepted Reply

Replies