[RFC] Documentation improvements

[andersio]

Changes

1. Group methods by the extension constraints. Say skipNil() is now under the section Error == NoError.

   https://andersio.github.io/ras-1.1.1/Classes/Signal.html
   https://andersio.github.io/ras-1.1.1/Structs/SignalProducer.html

2. Remove SignalProtocol, SignalProducerProtocol, EventProtocol and OptionalProtocol from the documentation, since these are implementation details.

   This requires affected constraints to be expressed in a parametric form. The current implementation uses the form in the Swift Generic Manifesto. For example, Value: OptionalProtocol would be expressed as <U> Value == U? instead.

3. Reactive extensions of NotificationCenter and URLSession would now show up as individual top-level declarations.

   https://andersio.github.io/ras-1.1.1/Reactive%20Extensions/NotificationCenter.html

/cc @ReactiveCocoa/reactiveswift

[mdiep]

I'm not totally sure what you're suggesting. 😕

Probably because I'm mostly unfamiliar with the generated docs.

[andersio]

@mdiep I have customized Jazzy to generate better docs for RAS and RAC, and looking for comments on the changes.

1. Methods are now grouped by the extension constraints. Say skipNil is under Value: OptionalProtocol.

   Now: http://reactivecocoa.io/reactiveswift/docs/latest/Classes/Signal.html
   New: https://andersio.github.io/ras-1.1.1/Classes/Signal.html

   But since OptionalProtocol is more like an implementation detail until we have parametric extensions, the constraint is substituted by its parametric form <U> Value == U?. SignalProtocol, SignalProducerProtocol and EventProtocol are all substituted similarly.

   The downside of grouping by constraints is obviously breaking the code-based organisation.

   One possible alternative/complement is having all extension methods specifying its constraint in its name. So instead of skipNil() in the list, it would be shown as skipNil() where <U> Value == U?

2. Reactive extensions now get their own separate pages on a per-type basis, instead of all showing up under Reactive.

   Now: http://reactivecocoa.io/reactiveswift/docs/latest/Structs/Reactive.html
   New: https://andersio.github.io/ras-1.1.1/Reactive%20Extensions/NotificationCenter.html

   You can also check how the RAC docs would look: https://andersio.github.io/rac-5.0.3/.

   One thing I am not sure about is whether these should show up as specialised Reactive, or just their base name e.g. Reactive<UIView> vs UIView.

   The navigation does give them special treatment, i.e. "Reactive Extension". But however in Dash they show up in the tables of content as "Extension", since Dash doesn't allow custom entity type.

   

[mdiep]

I like it. 👍

[RuiAAPeres]

Hello. 👋 Thanks for opening this issue. Due to inactivity, we will soft close the issue. If you feel that it should remain open, please let us know. 😄