Extension shown as undocumented when class is undocumented

[Nef10]

If a class is not documented, e.g.

public class TestNoComment {

    /// Test
    public var a = "test"
}

extension TestNoComment : CustomStringConvertible {
    /// just returns a
    public var description: String {
        return a
    }
}

The undocumented.json shows a warning for the class as well as for the extension:

{
  "warnings": [
    {
      "file": "/Users/Steffen/Projects/JazzyCategories/JazzyCategories/TestNoComment.swift",
      "line": null,
      "symbol": "TestNoComment",
      "symbol_kind": "source.lang.swift.decl.extension",
      "warning": "undocumented"
    },
    {
      "file": "/Users/Steffen/Projects/JazzyCategories/JazzyCategories/TestNoComment.swift",
      "line": 11,
      "symbol": "TestNoComment",
      "symbol_kind": "source.lang.swift.decl.class",
      "warning": "undocumented"
    }
  ],
  "source_directory": "/Users/Steffen/Projects/JazzyCategories"
}

I find this pretty confusing because there is no way to comment an extension - I mean sure I can do

/// Custom String Representation
extension TestNoComment : CustomStringConvertible {

but this will neither be shown anywhere nor silence the warning.

The other weird this is that the line is null.

I am not 100% sure, but could we just remove the warning for the extension because a warning for the class is already shown?

[SDGGiesbrecht]

There is no way to comment an extension.

Not in Swift proper, but Jazzy does support this. Such support is aimed at extensions to types outside the module.

In addition, Jazzy displays extensions together with the base type if it is available, effectively merging them.

@Nef10, the particular oddity you noticed is the unusual corner case where these two functionalities overlap:

1. Since the type definition is in the module, the extension is merged into the type definition (and the extension’s line number, now meaningless, is dropped. This is the reason for "line": null.)

2. Since the type is undocumented, an error is thrown for the type. (Apparently the merge still has some left‐over data that results in a duplicated error thrown for the extension. The duplicate is definitely a bug.)

---

Note that if you deal with the error for the class, the error for the extension will stop bothering you too.

If you document the type,

1. The extension will be merged into the type and the type’s documentation will be displayed.

2. The extension methods will be included in the type’s method list.

3. Jazzy will ignore the presence or absence of Jazzy‐only documentation for the extension.

4. No errors will be thrown.

This is known to work correctly. (Here is an example where methods have been collected from many different extensions. None of the extensions have Jazzy‐only documentation, but the module is still 100% documented. Extension spread like this is far more common for protocols than structures or classes.)

If you move the type into a dependency module,

1. If there are multiple extensions, they will be merged into one.

2. It will be displayed as an extension, and will include Jazzy‐only documentation if provided. (Behaviour is undefined if you provide separate Jazzy‐only documentation to two distinct extensions.)

3. No errors will be thrown. (Because two extensions cannot be documented simultaneously, because Jazzy is the only tool aware of that documentation, and because the onus for documentation really belongs on the other module.)

This is also known to work correctly. (Here is an example of such an extension to Foundation.Data. The extension adds no documentation, but the module is still 100% documented.)

[Nef10]

Thank you for your detailed explanation!

[johnfairh]

Keeping this for the buglet of putting extensions into undocumented.json.