docs(_dev-doc): introduce the _dev-doc feature

[ROMemories]

This introduces the _dev-doc Cargo feature, which allows us to hide some items from users by default and only show them to developers when this feature is enabled.

---

All items that should be hidden to users may not be part of this PR, you can propose them here or we'll progressively add them; this PR mostly aims to lay the groundwork for easily adding them in the future.

---

We will soon build another version of the docs, aimed at users, with the _dev-doc feature disabled.

[ROMemories]

This feature is not part of the visible docs on purpose, as it's only aimed at developers.

[elenaf9]

If I understand correctly, this features is used for functions/ modules that users don't need to care about if they are using our macros.
I haven't seen this pattern/ design before. In what scenario would it be useful? So far I only used #[docs(hidden)] for restricting what is showed on docs.rs, but aren't there all features enabled anyway?

I think I would prefer not to hide the items. Instead I think we should add docs explaining their purpose and when/how they should be used.

Edit: also I think the term "developer docs" is confusing. What developers are you referring to? If anything, I understand it more as an "expert mode"; for users who know what they are doing.

[ROMemories]

I haven't seen this pattern/ design before.

This originates from the use of numerous crates in a workspace, where we need to export some items from our child crates and use them in parent crates (while not being part of our user-facing, public API), mostly due to our heavy use of linkme::distributed_slice and of macros.

In what scenario would it be useful? So far I only used #[docs(hidden)] for restricting what is showed on docs.rs

All #[doc(hiden)] would become #[cfg_attr(not(feature = "_dev-doc"), doc(hidden))] (there is exactly one of them in the codebase currently, which is replaced as part of this PR), which allows developers to use the rustdoc docs to have a better grasp of the actual API surface of each workspace crate, even when some items are hidden from users.

but aren't there all features enabled anyway?

I'm not sure what you mean by this. docs.rs allows to select the set of features we want (and we would not enable _dev-doc there); as for our docs hosted on GitHub Pages, we will have two versions: one for users (_dev-doc disabled) and one for developers (_dev-doc enabled).

I think I would prefer not to hide the items. Instead I think we should add docs explaining their purpose and when/how they should be used.

If we did that, these items would become part of our API and of our (future) SemVer commitment, which we want to avoid for what's only cross-crates implementation details.

also I think the term "developer docs" is confusing. What developers are you referring to? If anything, I understand it more as an "expert mode"; for users who know what they are doing.

Here, "developers" are RIOT-rs developers, users are application developers.

[elenaf9]

Thanks for the clarification; I noticed I slightly misunderstood the purpose of this feature.

If we did that, these items would become part of our API and of our (future) SemVer commitment, which we want to avoid for what's only cross-crates implementation details.

You're right, I didn't think of that. But if we decide that these items only for internal usage, I would be in favor of just making it hidden.

which allows developers to use the rustdoc docs to have a better grasp of the actual API surface of each workspace crate, even when some items are hidden from users.

I'd argue that this is a rather niche use-case. Developers could also just look at the rustdocs docs, and then look what additional items there are that are doc(hidden). I also think the number of items in this category is limited.

---

I see the pro's of this features, but I still think it might be more confusing that helpful. But I don't feel strongly about it; curious to hear what other folks think.