Luke Boswell (Jun 11 2023 at 23:12): Luke Boswell (Jun 11 2023 at 23:12):I have noticed that the ordering of Modules in generated docs changes frequently between generation. I feel like there should be a consistent ordering here. I propose we sort the Modules, possibly alphabetical if that is possible? Are there any other considerations here?
Another other related idea, is that I think we should always have the Types first, and then have the functions below that, also sorted alphabetically. Currently the generated docs reflect the order they are defined in the module. I think the main downside of the current strategy is that even when you know the name of a function, you can easily miss it when looking at the list of functions because they are not in order.
Richard Feldman (Jun 12 2023 at 02:18):I think the modules should be sorted by the ordering they're exposed in
Richard Feldman (Jun 12 2023 at 02:19):I think that's valuable for being in control of how people encounter them for learning purposes
Richard Feldman (Jun 12 2023 at 02:19):e.g. if alphabetically, AdvancedModuleThatAlmostNeverGetsUsed is first, that's not ideal for someone clicking through the docs to learn things :big_smile:
Hannes (Jun 12 2023 at 14:06):Agree on using the order they were exposed in, for example in the HTML module it's useful to have the render function listed first and then all of the HTML element functions
Luke Boswell (Jan 27 2024 at 03:11):Further to this, this PR for this issue is to re-order docs so that functions for a module (like List) are displayed in alphabetical order.
Just wanted to confirm this was the desired behaviour, as the above thread had me thinking we wanted the opposite behaviour.
@Stuart Hinson
Anton (Jan 27 2024 at 09:36):Perhaps we should default to the exposed order and add a button that can put them in alphabetical order?
Luke Boswell (Jan 27 2024 at 10:53):I like that idea
Anne Archibald (Feb 04 2024 at 11:08):Documenting functions in the exposed order allows module writers to order the functions in a way they deem logical (would a way to add dividers to the automated docs be nice? One convention is to include page-break characters in source code). This can of course be alphabetical if no more logical choice suggests itself.
Of course, there are potentially two orders that are exposed by a module: the order definitions appear in the source code, and the order they are listed in the exposes list. Which of these to use is less clear; maybe the exposes list order allows the code to be ordered in a way that makes sense for readers of the code and the exposes list in a way that makes sense for readers of the docs? Or just alphabetise the exposes list in the formatter to make clear that it's order is irrelevant?
Of course, bring able to re-sort the website is very useful regardless.
Richard Feldman (Feb 04 2024 at 12:13):using the exposes list is more friendly to VCS diffs; you can change the ordering without having to redo the entire source file :big_smile:
Last updated: Jun 16 2026 at 16:19 UTC