Parameter to exclude overridden functions & properties.

[MrAlek]

Currently, you can use the :nodoc: token to exclude specific declarations but in cases where you have to do many overrides (such as a framework of UIViews), completely ignoring all overrides in the generated documentation would make life much easier for a framework maintainer.

Generally speaking, this makes sense for a lot of object oriented frameworks where overrides is usually common. Apple's own documentation for instance, doesn't state overridden functions because they are part of the parent interface. An --exclude-overrides parameter would be great for these cases.

[garricn]

I can imagine being frustrated with having to write that a bunch of times. By the way, thanks for mentioning /// :nodoc: , it works great!

[pigeon-archive]

Thanks for submitting this. I'm going to consider this a feature request. We don't currently have the bandwidth to implement this ourselves but we'd happily review a PR if you can submit one with the change. Cheers! :)

[SDGGiesbrecht]

A word of warning about /// :nodoc:: It is Jazzy‐only. Quick Help does not understand it.

I used to use /// :nodoc: for overrides, but then I realized Quick Help displays “:nodoc:” to anyone who ⌥‐clicks the symbol or looks at the Quick Help tab. Duplicating the documentation is admittedly annoying, but that’s still the only thing that satisfies Quick Help.

(/// :nodoc: is, however, perfect for symbols that take the form _pleaseDoNotUseThis() and are only begrudgingly declared public.)

⁂

That being said, if someone decides to implement this anyway, it would be wise to treat overrides of all the following forms the same for consistency’s sake:

• class method → subclass override
• protocol method → default implementation → more specific, optimized default implementation
• generic function → more specific, optimized generic function

[paulofaria]

Duplicating the documentation is admittedly annoying, but that’s still the only thing that satisfies Quick Help.

what do you mean by this? how can I hide :nodoc: from quick help?

[SDGGiesbrecht]

@paulofaria

how can I hide :nodoc: from quick help?

You can’t.

If you want to satisfy Quick Help, you have to manually copy and paste the entire documentation comment from the superclass method to the subclass method.

Since my previous post I have built some automation for this into another tool called Workspace. The documentation for this specific functionality is here.

For now, you still have to opt into it manually for each method, but once you do, the documentation comments are locked in sync with each other. It is on my to‐do list to make Workspace capable of finding the superclass method without manual guidance, but I might not get to it for a while.

[paulofaria]

oh that's too bad! :( thanks for the info