Allow user control over documentation landing page

[LeventErkok]

It seems to me that when haddock generates a hackage landing page (such as https://hackage.haskell.org/package/lens for an example), it will list the exported modules always in alphabetical order.

I think it would be nice to give users control over what the order should be. For instance, if there's an internal module being exported, you might want that not to clutter other modules that are more important.

I'm thinking that at least when invoked from 'cabal', haddock can look at the order someone listed their exported-modules list and respect that order as it generates the landing page; instead of going purely alphabetical. (This could, of course, be an option as well.)

Is this something easy to do? Would it be desirable? I'd for one would like to have this and cannot see any down sides, but perhaps there's good reason for keeping things as is.

[harpocrates]

While haddock does support creating index pages (and this would be an applicable request), the ones on Hackage are actually generated by Hackage Server, so this feature request probably belongs over there.

My two cents:

• This could definitely be handy, but I'm concerned about making the output less predictable.
• Listing things alphabetically has the nice property that you can use indentation to draw out the tree-structure of the modules. Not sure what to do if the order of modules is no longer an in-order traversal of the module tree...

[gbaz]

The question is how we could signal the user's preference in a way that haddock and hackage-server would both notice and respect it?

[hvr]

IMO, it'd be rather confusing to have packages on Hackage have a customized ordering of the module tree, and it would make it harder for Hackage to change the way it lays out the the module tree in in the web-ui in future if we'd have to honor some pre-decided layout/ordering. Also note that Hackage isn't the only tool displaying the set of exposed modules; there's also CLI tooling such as cabal info pkgname which gives you the list of dumped modules; and ghc-pkg describe similarly allows to introspect a list of modules. So if we really want to control how exposed-modules are rendered, then we'd have to take into account all those other potential consumers as well in the design.

[LeventErkok]

@hvr Consistency is a good point indeed. But isn't the whole point of a hackage landing page is to help users see what's important and expose the API in the most natural way they should see. Alphabetical order hardly achieves that.

I admit to playing games with my module names so the alphabetical order and my "logical" order would match. I wonder if others had similar experiences. That is precisely what I'm trying to avoid.

But I agree that consistency is a key feature; that's why I imagined this would be a cabal file field and all the tools can adhere to it that way; so long as there's a cabal file associated.

[harendra-kumar]

I wanted to raise the same issue with exactly the same points. I want the Internal module to be out of the way, at the end, there may be so many of those that it becomes difficult to find the documentation of exposed API. We can choose to hide the internal documentation (OPTIONS_HADDOCK hide) but the internal documentation can also be useful to understand the package. We can name the internal module to something like ZInternal but that's an ugly hack.

Even if the author can control whether a module shows expanded or collapsed in the output can also help. We can keep the Internal module as collapsed so that it does not show as a big distraction in the middle.

The default ordering of modules should be in the hands of the author of the package. The generated html listing can provide a sort option if the user viewing the documentation would like to change the default to alphabetical.

I consider this issue as a very important one because I consider the ability to browse the package documentation conveniently as a very important aspect of the software.