Generic types in functions required to be documented

[nvzqz]

When working with generic type parameters in global functions, jazzy insists that they should be documented. However, there is no way to document it and thus it just shows up as "Undocumented".

[jpsim]

Sorry for the lack of comments here @nvzqz, could you please check against the latest version of jazzy (0.6.0), a few improvements were made in this area so I'd love to know if this is still an issue so we can decide if we should invest some time into fixing this.

[diliedevs]

I'm using jazzy 0.6.0, but am still getting undocumented for generic types like T. I don't know how to document that. Hoping for a fix soon! I don't like it when my code is not 100% documented.

[yarneo]

+1

[maddiemort]

Still getting this with jazzy 0.7.2.

[pigeon-archive]

We'll need to investigate this further. Anyone interested in tackling this?

[SDGGiesbrecht]

As of 0.7.3, this is still a problem.

The following is an update‐to‐date, specific and consice description:

Jazzy treats generic type parameters as undocumented symbols. This results in an incorrect (deceptively low) documentation coverage percentage being displayed.

The undocumented.json output contains entries of the form:

    {
      "file": "/Path/To/File.swift",
      "line": 7,
      "symbol": "function(_:).T",
      "symbol_kind": "source.lang.swift.decl.generic_type_param",
      "warning": "undocumented"
    },

Compare this source with [this output] the output of the following test.
[Edit: The above linked documentation will soon be regenerated with a forked version of Jazzy where the bug has been fixed. See subsequent comments.]

To test it yourself, simply run the following terminal commands:

git clone https://github.com/SDGGiesbrecht/SDGLogic
cd SDGLogic
swift package generate-xcodeproj
jazzy
open docs/index.html
open docs/undocumented.json
cd ..

Coverage should be 100% and undocumented.json should be empty.

[SDGGiesbrecht]

I submitted a pull request with a fix.

Until it is accepted, you can clone my fork at https://github.com/SDGGiesbrecht/jazzy, checkout the fix-429-generic-types branch, build jazzy from source (Instruction are under “Development”) and run the modified version.

[pigeon-archive]

Awesome, thanks for filing the PR. I'll get someone to look at it stat. :)