Add documentation of functions in Documentation Catalog

Evolution Pitches
,
1

Normally when writing documentation directly in the source file and the Documentation Catalog, it more or less looks something like this

Source file

/// <#Description#>
class ClassName {

    /// <#Description#>
    public let shared = ClassName()

    /// <#Description#>
    func noParams() {

    }

    /// <#Description#>
    /// - Parameter param: <#param description#>
    func singleParam(param: Double) {

    }

    /// <#Description#>
    /// - Parameters:
    ///   - param1: <#param1 description#>
    ///   - param2: <#param2 description#>
    ///   - param3: <#param3 description#>
    ///
    /// Discussion about functions here
    func multipleParams(param1: Int, param2: Float, param3: Int) {

    }
}

Documentation Catalog

# ``PackageName/ClassName``
@Metadata {
    @DocumentationExtension(mergeBehavior: append)
}

discussion about how to use class

it works nicely but as you add more and more methods and properties to this class it becomes very ugly because of all that comments.

so I would like to write something like this in the Documentation Catalog for the documentation of my functions and remove documentation from the source to keep it readable

# ``PackageName/ClassName``
@Metadata {
    @DocumentationExtension(mergeBehavior: append)
}

discussion about how to use class

## ``noParams()``
doc for noParams function

## ``singleParam(param: )``
- Parameter param: <#param description#>

is there any other way of doing this that I might have missed?

I am using XCode 13.2.1 right now so I am not sure if a similar feature already exists in the newer XCode versions

2

I believe you can make extension articles for individual methods, I haven't tried but I don't see why it wouldn't work.

Instead of MyPackage/MyClass your title would be MyPackage/MyClass/myMethod just as you'd put it if you were linking to it.

1 Like
3

I believe you can make extension articles for individual methods

I have tried it and it works,

but if you do it then you will need multiple files for every function
so there will be tons of files for us to manage and it can be troublesome to update any specific function's documentation

4

I usually keep the summaries and parameter docs (along with critical info) in case someone is browsing the source code and only add extensions when I want to provide more in-depth information or examples, which isn't all that common for functions (I usually put examples on the type docs and functions link to it).

Personally I haven't found the docs to be all that distracting or "ugly" and their presence near their symbol has often been helpful, both to me and external readers (like reviewers).

5

Documentation extensions are for a single symbol by design. They are primarily meant for two use cases:

  • When you include thorough code examples, long form discussions, and/or illustrations that increase the length of your documentation markup and make source files difficult to manage
  • When your source documentation comments focus on the implementation of your
    code, and aren't appropriate for external documentation

My personal thoughts on this is that if the documentation you are moving to extension files is short enough that you feel that it'd be easier to manage multiple symbol's documentation in the same extension file then it may be that none of those symbol's merit a documentation extension file and that it would be easiest to manage their documentation in-source.

One benefit of in-source documentation is that you or other contributors to your project can read the documentation while reading the code without switching to the rendered version of the documentation (either using IDE features or using a separate browser window). This can for example be a useful when actively working on that code of when reviewing someone else's changes to that code.

2 Likes