Combine Structs and Enums sections?

[stdsync]

First let me say that I think the docs are excellent (especially for this stage of the language).

One thing that I think would make it easier to find APIs is to combine the overview of Structs and Enums on the module landing pages. The user of a library often doesn’t care how a certain opaque type is implemented behind the scenes, and it is confusing to find them under two headings.

The different colors can still be used to distinguish, of course, and maybe an “(Enum)” appendix.

[stdsync]

Bump?

[steveklabnik]

combine the overview of Structs and Enums on the module landing pages.

Sorry, what is the ‘module landing pages’ here?

[stdsync]

For example https://doc.rust-lang.org/std/net/index.html

[steveklabnik]

Ahh, I see.

I don’t know, in systems programming, you care about the details. Structs and enums are different.

[stebalien]

One does care about the details eventually but this is an index; details can be put on the description page.

I can’t speak for everyone, but when I go to a module’s index to look something up, I know if I’m looking for a type, function, or module but I generally don’t know ahead of time if I’m looking for an enum or a struct. Quite often, enums are hidden inside wrapping structs (e.g. io::Error) so even if I think I’m looking for an enum, I might actually be looking for a struct (or vice versa e.g. borrow::Cow).

Note: I don’t really feel that strongly about this because type lists are generally pretty short anyways (and I usually just search).

[stdsync]

Quite often, enums are hidden inside wrapping structs (e.g. io::Error) so even if I think I’m looking for an enum, I might actually be looking for a struct (or vice versa e.g. borrow::Cow).

Yes, that was my thinking as well. It’s obviously not a big issue though.

[derekdreery]

I had this thought the other day as well. If all fields a private and you just use accessor methods, then you don’t really care whether it’s a struct or an enum. So the separation introduces extra cognitive load for no benefit.

You definitely couldn’t combine them for everything. You could maybe let the consumer decide to combine them as they are reading the documentation, or allow the producer to combine them, or do it automatically if there are no public fields.

But the this introduces complexity into the documentation code, and possibly extra config options. Not sure if it’s worth it.

[derekdreery]

Another idea (from Elm)

Have an opt-in way of writing module documentation, where you specify the order that the module contents are displayed. You must include all contents exactly once. See elm-docs#documenting-a-module.

EDIT: Yet anothe possibility is to encourage use of public modules with re-exports, where the modules help to show the hierarchy of structs/enums.

[system]

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.