Documentation links convention

help
#1

Hello !

I wanted opinions on documenting code: do you think it is better to do

/// ... some doc ...  [`OtherStruct`] ... [`OtherStruct`]
///
///  [`OtherStruct`]: path::to::OtherStruct
pub struct MyStruct;

Or

/// ... some doc ...  [`OtherStruct`] ... `OtherStruct`
///
///  [`OtherStruct`]: path::to::OtherStruct
pub struct MyStruct;

In other words, should every occurrence of OtherStruct be linked, or only the first one ?

#2

If you look at something like std::collections - Rust you'll find that every occurence of Vec (and other collections) is linked, so I think the convention is to link every occurrence.
I think it's more convenient to have it linked every occurrence so that you don't have to manually go to the docs or find the one link in the page.

#3

I usually link the first occurrence in each paragraph.

#4

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.