[RFC] Documentation sections

[asterite]

After @rosylilly's great enhancements to the API docs, many things still remain.

One of them is that all the types in the left are just listed alphabetically. Maybe it would be nice to group them in sections. For example: "Core" (Object, Bool, Char, etc.), "Containers" (Array, Hash, Set, BitArray, etc.), "IO", "Networking" (Socket, HTTP::Client, etc.), "File formats" (Ini, JSON, XML), "Spec" (Spec), etc.

One idea is to put this section in the docs themselves, for example:

# :section: Networking
#
# The HTTP module blah blah blah...
module HTTP
end

Sections could be nested, for example :section: Networking / HTTP. The documentation generator would read the first line of a type's docs to determine the section, and from all the sections it could build the left navigation.

This idea was suggested by @waj. At first I though this might only make sense for the standard library, but it's true that big libraries (frameworks) might provide many functionalities and it would be nice to have classes with related functionality grouped in the docs.

[jhass]

:+1: sounds like a good idea. Yard does that even on the class level listing / method level with @!group.

[TheLonelyGhost]

From experience so far in searching the API documentation, I find it more useful to use the search box. Perhaps instead of using a hierarchical approach like with sections, would it make more sense to have keyword metadata like below? The search bar could then filter through the list of modules for any that match either the name or one of the keywords.

# :keywords: Networking | HTTP | REST | API | Web
#
# The HTTP module does a bunch of stuff that we care deeply about ...
module HTTP
  # [...]
end

It might make more sense in a different context, such as with channels. Keywords like Concurrent, Concurrency, Thread, Fork, and so on would be relevant to the channels API, enough to point people in the right direction.

[devnote-dev]

To expand on this: having the different constructs grouped in their own sections too by default (i.e. modules, classes, structs, etc). I was recently trying to search for a specific annotation in the standard library, but there was no sane way to do that...

[konovod]

1. Grouping is definitely very nice feature and is needed not only in stdlib
2. Right now grouping is possible using modules:

   # This module includes everything about networks...
   module Networking
   # The HTTP module blah blah blah...
   module HTTP
   end
   end
   include Networking # so API won't change

   and i am actually using this way.

Pro:

• you can also add description to the entire section

Contra:

• changing a source to make documentation cleaner doesn't feel right.

[Blacksmoke16]

The other con is that it can lead to longer type names, but top level shorter alias can be a good workaround.