Rustdoc shows impls out of source order

[jyn514]

I'm torn on this. On one hand, this is clearly distorting the SGX docs: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#asynchronous-usercalls

Due to rustdoc, this section may appear at the top of the Usercalls documentation. You might want to read the other sections first and then come back to this one.

On the other, SGX is sort of abusing rustdoc here. Maybe we should suggest using modules to group the docs instead of impl blocks?

The other issue is that if rustdoc does this, it will look very strange for impls without a doc-comment.

cc @jethrogb, git says you wrote those docs.

[jethrogb]

I'm not sure what this issue is about.

Regarding my comment: Generally, things appear in rustdoc in the order they appear in the source code. For that one impl block with my comment, it appears out of order with the source code for some reason.

What does a table of contents have to do with documentation ordering?

[Lonami]

This TOC would come in handy for me. I have one "god" struct as a high-level construct, and the impl blocks can get so large that I've split them across many files by topic (code).

I think there's value here, but I'm not sure what the best way to add a TOC would be. Maybe only generate it if there's more than one impl block? It could get confusing if not all are documented as you say though, but only generating it if all blocks are documented could be even more confusing.

[the8472]

Related #40273 #14475

[jyn514]

Regarding my comment: Generally, things appear in rustdoc in the order they appear in the source code. For that one impl block with my comment, it appears out of order with the source code for some reason.

Oh, I didn't realize that from the comment. I see - the issue is that rustdoc processes the submodules (async) before the impls in the current module (starting with 'Streams').

I'll change this issue to track that bug instead, since it sounds like #40273 is already tracking the table of contents issue.

[camelid]

I have this issue in a personal project as well: I have a parser that's split up into several submodules and each submodule has an impl Parser. rustdoc shows the submodules' impls before the top-level module's impl.

Even if I put the mods at the bottom of the file, it still shows their impls first.