rustdoc: show macro interface but not implementation

[kmcallister]

e.g. http://doc.rust-lang.org/std/macro.bitflags!.html has 120 lines of macro code before anything useful.

[gamazeps]

Hi, i'm a bit new to rustdoc (but willing to learn ;) )
How would you change the order of the doc and the code, as the doc is already written before the code in http://doc.rust-lang.org/src/std/home/rustbuild/src/rust-buildbot/slave/nightly-linux/build/src/libstd/bitflags.rs.html ?

[jdm]

You would probably want to reverse the order of calls in item_macro in html/render.rs (http://mxr.mozilla.org/rust/source/src/librustdoc/html/render.rs#2183).

(For the record, I determined this by grepping the librustdoc for the word 'macro')

[gamazeps]

Thx :)
I checked the doc of another file (c_str.rs) and the only visible difference betwen the two of them was the fact that the doc was written with instead /*! ... */ of ///.

But looking at other macros in std, it seems that the code beeing present before the doc is a recurring issue...

Anyways, thaks a lot for the answer (you kinda fixed the issue yourself ^^)

[gamazeps]

Switching the two function calls somehow works, yet the traits, methods and example stay after the implementation. Is that good eough @kmcallister ?
I'll look into it a little more tonight

[gamazeps]

@kmcallister look at @alexcrichton comment on the PR, this issue can be closed

[kmcallister]

cc @alexcrichton

If the rule is that definition always comes before docs, then it's a problem that we document macros like structs or enums rather than like functions. We certainly don't want to put the full source of every function before its description.

And I think there will be plenty of macros as large as bitflags!. A sophisticated macro abstracts in the same way a function does; you don't need to understand the full implementation to use it. If we put the full implementation in rustdoc, that suggests that macros are merely for convenience in abbreviating code, which limits the usefulness of the feature.

Maybe the simple fix is a #[doc(summarize)] attribute for macro_rules! that just leaves off the RHS (which is still visible through the "src" link.)

[alexcrichton]

While we don't put the full source of functions/items/etc, we do put their interface. The interface of a macro is how you invoke it, which is the bare minimum of what must be displayed, and currently it does this by displaying the whole macro. A better solution to that problem in my opinion would be to only show the arms of the macro that provide information about how to invoke it, not what it generates.

[kmcallister]

A better solution to that problem in my opinion would be to only show the arms of the macro that provide information about how to invoke it, not what it generates.

Agreed. If we move some code around, we can parse into LHSes and RHSes on macro definition, and then have rustdoc display only the former. I think I can get this in place for 1.0-stable.

[kmcallister]

Not going to have time to work on this for 1.0-final, sorry.

[nixpulvis]

FWIW I also had the exact same thought when looking at the documentation for bitflag! as well. The proposed change to only show the left arm of the macro would look like this.

macro_rules! bitflags {
    ($(#[$attr:meta])* flags $BitFlags:ident: $T:ty {
        $($(#[$Flag_attr:meta])* const $Flag:ident = $value:expr),+
    }) => { ... },
    ($(#[$attr:meta])* flags $BitFlags:ident: $T:ty {
        $($(#[$Flag_attr:meta])* const $Flag:ident = $value:expr),+,
    }) => { ... },
}

A welcome change.

[m4rw3r]

I have a similar issue, though it cannot easily be solved by just showing the left arm of the macro since there are multiple internal rules and they refer to each other: https://github.com/m4rw3r/chomp/blob/60cb0fb111e079c472c02821cee5e82b0eef2b82/src/macros.rs#L71

If we just go with the left arm of the macro it will result in a lot of nonsensical entrypoints:

macro_rules! parse {
    ( @RET($i:expr); @ $t_ty:ty , $e_ty:ty : $e:expr ) => { ... };
    ( @RET($i:expr); $e:expr ) => { ... };
    ( @ERR($i:expr); @ $t_ty:ty , $e_ty:ty : $e:expr ) => { ... };
    // ...
    ( $i:expr ; err $($tail:tt)+ ) => { ... };
    // ...
    ( $i:expr ) => { $i };
}

And skipping the internal rules will make the macro even more incomprehensible since the entrypoints themselves just parse a bit of the tokens for each invocation.

For my case I would think that just hiding the whole macro definition would solve the problem (maybe with some button to expand the definition), since I have to explain how the macro is used anyway since it by itself says nothing unless people are very experienced with rust macros.

As a workaround I have defined a hidden macro which contains the actual definition: https://github.com/m4rw3r/chomp/blob/5016d0b9e636156927e514f430e33510d9fa94f7/src/macros.rs#L76