Rustdoc documentation

I am looking for some documentation for rustdoc

I have seen https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html but it is not what I need.

What I need is instructions on how to use the system, both correctly and idiomatically.

For example I have been reading source code to try to deduce some things for my self and have struck: //!. I have no idea what that is and cannot find it in the documentation (I have found so far).

There is a lot else I do not know, is it written down some where?

I don't know of any official documents (Other than this), but I can give you a pretty quick rundown of how it works:

// This is a regular comment, which isn't included in anything
///This is a rustdoc comment, which is included in the #[doc] atttribute
///of the next item:
fn foo() {}
// Hence `foo` becomes:
#[doc = "This is a rustdoc comment, which is included in the #[doc] atttribute of the next item:"]
fn foo() {}
// We can also document modules:
///Stuff, stuff and some more stuff... y'know, the stuff which we code...?
mod stuff { }
// Similarly this becomes:
#[doc = "Stuff, stuff and some more stuff... y'know, the stuff which we code...?"]
mod stuff { }
// But what if we wanted to document our crate?
// We could just introduce a weird function or... or...
// We just use a special rustdoc comment:
//! This is the crate description, which wouldn't usually compile
//! because this, similarly to attributes applied to the crate,
//! need to be at the top of the module declaration,
//! but lets ignore it for now.
// Now say I had something like this in a mod:
mod bar {
    //! Oh noes! are we documenting the crate?
    //! Nope, we're documenting the upper most level
    //! AKA `crate::bar::self` or `crate::bar`
}
//This is similar to mod/crate attributes:
#![doc = "This applies a `doc` attribute to the crate"]
mod foo_bar {
    //The following allows you to apply it as if it were declared on the module.
    #![allow(non_snake_case)]
}

That is a different documentation site. It may help.

I think it is unproductive me posting here every time I strike something I do not know or cannot deduce from examples so still hoping some body some where has written some documentation.... So much to do, by so few, for so many!! I will cope.

1 Like

This specific question isn’t answered in rustdoc’s docs because it’s a language feature, and so is documented in the book and reference.

Please don’t hesitate to open issues on the main rust repository if there are things that aren’t included in the rustdoc docs; we can’t fix problems we don’t know about.

1 Like