Documentation of Internal protocol is not inherited by conforming public types at documentation generation #7

Closed
opened 2025-09-10 17:00:43 +00:00 by javier · 1 comment
Owner

Summary

Either when generating or previewing the DocC documentation of the library via the command line, those public types that conforms to the APIClient, KeyNameFilter, and KeyNameModel internal protocols are not inheriting the documentation for its properties and functions from those protocols.

Explanation

Basically, the documentation of those properties and/or functions for the types conforming to those internal protocols mentioned in the Summary section have no documentation whatsoever. No matter if the documentation is being generated or preview from the command line.

I also tried including the --enable-inherited-docs flag inside the documentation tasks in the Makefile, that is documented in the help for the swift package generate-documentation or the swift package preview-documentation commands, without avail.

Steps to reproduce

  1. Preview or generate the documentation for the library by entering the make doc-generate or the make doc-preview in the command line.
  2. Wait for the documentation compilation and build to finish.
  3. Open the documentation either in the Xcode documentation browser or in the Safari web browser.
  4. Check the properties and functions on one of the following types for any documentation:
  • AmiiboLiveClient
  • AmiiboMockClient
  • AmiiboSeriesFilter
  • AmiiboTypeFilter
  • GameCharacterFilter
  • GameSeriessFilter
  • AmiiboSeries
  • AmiiboType
  • GameCharacter
  • GameSeries

Extra details

When generating the DocC documentation directly from Xcode, either by selecting the Product > Build Documentation option from the menu or by using the Control + Shift + Command + D shortcut keys; this issue doesn't occur as any property and/or function of the types conforming to those internal protocols mentioned in the Summary section actually do inherit the documentation written from the m mentioned protocols.

However, this way of generating the DocC documentation doesn't make use of the AmiiboService documentation catalog in the Catalogs folder of the library unless the documentation catalog is located inside the library folder.

# Summary Either when generating or previewing the `DocC` documentation of the library via the command line, those public types that conforms to the `APIClient`, `KeyNameFilter`, and `KeyNameModel` internal protocols are not inheriting the documentation for its properties and functions from those protocols. # Explanation Basically, the documentation of those properties and/or functions for the types conforming to those internal protocols mentioned in the *Summary* section have no documentation whatsoever. No matter if the documentation is being generated or preview from the command line. I also tried including the `--enable-inherited-docs` flag inside the documentation tasks in the `Makefile`, that is documented in the help for the `swift package generate-documentation` or the `swift package preview-documentation` commands, without avail. # Steps to reproduce 1. Preview or generate the documentation for the library by entering the `make doc-generate` or the `make doc-preview` in the command line. 2. Wait for the documentation compilation and build to finish. 3. Open the documentation either in the *Xcode* documentation browser or in the *Safari* web browser. 4. Check the properties and functions on one of the following types for any documentation: * `AmiiboLiveClient` * `AmiiboMockClient` * `AmiiboSeriesFilter` * `AmiiboTypeFilter` * `GameCharacterFilter` * `GameSeriessFilter` * `AmiiboSeries` * `AmiiboType` * `GameCharacter` * `GameSeries` # Extra details When generating the `DocC` documentation directly from Xcode, either by selecting the `Product > Build Documentation` option from the menu or by using the `Control + Shift + Command + D` shortcut keys; this issue doesn't occur as any property and/or function of the types conforming to those internal protocols mentioned in the *Summary* section actually do inherit the documentation written from the m mentioned protocols. However, this way of generating the `DocC` documentation doesn't make use of the `AmiiboService` documentation catalog in the `Catalogs` folder of the library unless the documentation catalog is located inside the library folder.
javier added the Kind/BugKind/Documentation
Priority
Low
labels 2025-09-10 17:00:43 +00:00
javier self-assigned this 2025-09-10 17:00:43 +00:00
Author
Owner

I'm closing this issue for the moment, as it is not a priority to fix it.

I'm closing this issue for the moment, as it is not a priority to fix it.
Sign in to join this conversation.