swift-doc

swift-doc copied to clipboard

While a discussion is underway on how to exclude certain methods and properties in #101, this PR adds an argument to the generate command to add the ability to exclude full top level symbols from the generated documentation.

This is done using an external file containing a list of line separated symbol names, like:

MyExcludedClass
MyMockClass

This PR:

• Adds an excluded-symbols argument in the generate command options that takes in a path to a file containing a line separated list of symbols to be excluded. Defaults to nil.
• Adds a new argument to the Module initialiser, taking in an array of exclusions and filters the symbols by them.
• Updates README and action.yml with the new argument.

Thanks for sharing this PR, @biocross. I really appreciate your taking the time to work on this.

I'm glad to see an alternative strategy to controlling the output of symbols in documentation (as opposed to a directive like @hidden or :nodoc:). However, I'm still not entirely sold on the idea in the first place... Have you needed something like this in your own projects? I'd be interested to hear examples of when a public API shouldn't be documented.

Hi @mattt!

For my use case, it's mostly been the documented symbols competing with more important information. Since there's no way to currently manually section / order the generated documentation instead of the default sectioning by symbol type (enums / structs / protocol), I decided to have an exclusion list to keep important information at the top. An example was to hide some unit testing related mock symbols, which ideally should be documented and included, but were being put at the top of generated documentation.

Alternatively, we might also be able to use this list to also create a new section at the bottom of the generated documentation instead of excluding them altogether (sort of the like a less important symbols sections).

I appreciate your expanding on that, @biocross. There's a discussion about how section headers / symbol organization should work in #107, and I'd be interested to get your take on that.

An example was to hide some unit testing related mock symbols, which ideally should be documented and included, but were being put at the top of generated documentation.

Curious to know more about this specific case. I wouldn't normally consider test-related symbols to be part of a public API (and therefore be documented) unless testing were the sole purpose of the module. Is there any reason why those mocks couldn't be internal and imported with the @testable attribute?

However, I'm still not entirely sold on the idea in the first place... Have you needed something like this in your own projects? I'd be interested to hear examples of when a public API shouldn't be documented.

I was looking for this feature when I came across this. I could describe a couple of use-cases I have, if it helps:

• Types exposed via typealiases.

  I have a lazy collection type, LazilyPercentEncodedGroups, which does percent-encoding as a 2-dimensional collection - the Element of the collection is itself another collection, consisting of either the 3 bytes of the percent-encoded codepoint, or the original codepoint if it was not encoded. This is a useful type for my internal use, but it's not so useful as a public API. Users should really call .joined() on this to collapse the 2D collection. So, for the public API, I've defined a typealias LazilyPercentEncodedUTF8<Source> = FlattenSequence<LazilyPercentEncodedGroups<Source>>.

  LazilyPercentEncodedGroups has to be public because it appears in a public typealias, but it isn't intended to be used directly. The constructor is internal and there is no way AFAIK to dig the underlying instance out from the FlattenSequence, meaning users should never encounter it.

• Associated types of protocol conformances for said types.

  As mentioned, the Element of LazilyPercentEncodedGroups is a collection called _PercentEncodedByte. As LazilyPercentEncodedGroups is public, the Collection conformance and associated Element type must also be made public.

  Similarly, I have a LazilyPercentDecoded type (which is public and intended to be used directly), with a custom, opaque Index. swift-doc lists the Index type separately, which clutters the type list. There isn't really anything anybody can do with the Index - it conforms to Equatable and Comparable as Collection requires, but has no other API.

  

  The same goes for custom Iterator types:

  

• Funky API design!

  Swift libraries often have exotic API designs in order to make their usage sites clearer and guide features such as generics and type-inference. I have an example in the same library with a set of types which should preferably be referred-to by KeyPath as a guide for type-inference!