Ordering Items in Sections

[halostatue]

I'm documenting a parsing grammar with @type and @typedoc, and I’d like to be able to change the order of the types section so that it isn't alphabetical. I was thinking something similar to the @doc meta: value approach could be used with a new configuration option:

# in a module
@doc order: 1
def foo…

@doc order: 2
def bar…

# in mix.exs
    functions_order_by: & if(&1[:order], do: &1[:order], else: &1),
    types_order_by: & if(&1[:order], do: &1[:order], else: &1)

I’m not sure if anyone else would want this, but it would allow for more thematic ordering to the documentation whether grouping is used or not (the order would be applied to the group the items appear in). As an alternative, something like order_in_section: :sort (the current behaviour) or order_in_section: :manual (the order in which they appear in the document).

[josevalim]

Hi @halostatue!

Honestly, I'd prefer to not add this feature. One of the benefits of ExDoc is consistency across community documentation. If we allow some docs to be ordered and others not, then a developer no longer has any guarantee that, if they are looking at certain docs, if they are ordered alphabetically or not.

I already partially regret groups, because it means navigating some libraries and modules is very different, but at least groups are quite more explicit.

[josevalim]

Closing this per the above.