Adding abstracts for synthesized methods or default implementations

Development Swift-DocC
1

I wanted to check in and see if there was a way to add at least abstracts for some of the automatically synthesized methods that come with protocol conformance.

I thought maybe adding an explicit Extension type file might work, but so far I've been unable to get that to work. That said, there may be some patterns or constraints that I'm not correctly following.

I picked an example (!= in this case), the symbol for which is Vector/!=(_:_:) and put together an extension file in the .docc directory. I tried putting it in a subdirectory name "Vector" first, then moved it back to the root. Since I couldn't easily name it the same as the symbol (due to Xcode constraints about naming it), I named the file "Vector_NotEqual.md".

Inside the file I have the content:

# ``Vector/!=(_:_:)``

@Metadata {
    @DocumentationExtension(mergeBehavior: override)
}

A test abstract for Not Equal from inherited content

## Overview

This is a really cool function that shows that two vectors aren't equal.

I tried it without the @Metadata stanza as well - but so far nothing has managed to get the abstract updated in the top list, no the overview shown in the symbol itself.

Are there constraints about where this file needs to be located that make a difference?
Is this generally something that should work for overriding my own content, but doesn't because this is a protocol conformance method?

When in the organized listing for Vector, it's not showing any abstract, but when I go to the page content itself it's showing me a comment about it being inheritable - roughly in the same place as an abstract might be:

Screen Shot 2022-01-27 at 10.03.23 AM
Screen Shot 2022-01-27 at 10.03.23 AM1660×842 36.7 KB

What am I missing to be able to provide content for these symbols?

(Granted, it's kind of a PITA to do and probably not worth the effort for such an obvious function, but since I can't seem to get it to work, I wanted to see if I'd run up against an existing limitation here)

1 Like
2

I would expect synthesised methods to be documentable via documentation extension files. Can you try prepending your module's name in the title (per this article)? e.g.:

# ``MyFramework/Vector/!=(_:_:)``

I would expect DocC to emit a warning when a documentation extension's title doesn't match a symbol though, otherwise the matchup failure just gets swallowed silently. If it didn't, this would be great bug to file :slight_smile:

1 Like
3

Brilliant - the more complete symbol reference did the trick. Once I changed Vector/!=(_:_:) to Euclid/Vector/!=(_:_:), the override worked perfectly, and I didn't even need the explicit override metadata setting in there.

I was able to remove:

@Metadata {
    @DocumentationExtension(mergeBehavior: override)
}

and still get the docs from the extension file dropped into place for the synthesized values.

3 Likes