Trailing doc comments in trait definition causes an error

[brendanzab]

trait_comments.rs

trait A {
    fn a();     /// doc comment
}

fn main() {}

error:

$ rustc trait_comments.rs 
trait_comments.rs:3:0: 3:1 error: unexpected token: `}`
trait_comments.rs:3 }

It seems to only be triple slashes that cause it - // comment compiles fine.

Edit: Interestingly it seems that this compiles fine:

trait A {
    fn a();     /// comment
    fn b();     // comment
}

fn main() {}

[Dretch]

In the first example the doc-comment comes after fn a() - even though it is on the same line. Doc-comments need to come before the item they apply to (except for inner doc-comments, which come inside their item).

// ... type comments, with only two slashes, are not doc-comments (meaning rustdoc ignores them), so the parser doesn't need to know which item they apply to.

The problem here is that the error message when doc-comments are used in places they don't belong is not very insightful.

[Dretch]

I will try and have a go at improving the error message, since this keeps coming up.

[brendanzab]

But seeing as it's a comment, shouldn't it pass the compilation ok? I wasn't generating any documentation here...

[Dretch]

That argument does make some sense.

On the other hand, if rustc didn't complain then you would likely never had
noticed that you were putting doc-comments in the wrong places - and when
you did eventually run rustdoc it would have assigned your comments to the
wrong items (or in some cases given you an error).

[brendanzab]

Oh I see. Re-reading the rustdoc article, it seems like /// is actually just sugar that expands to a doc attribute.

With that 'insider' knowledge, I now understand why this gives an error:

fn main() {}

/**
*/

A scenario in which this would crop up would be:

fn main() {}

/**
 * Doc comment for foo
 */
// fn foo() {
//     io::println(~"foo")
// }

$ rustc rustdoc_breakage.rs
rustdoc_breakage.rs:3:1: 6:0 error: expected item
rustdoc_breakage.rs:3 /**
rustdoc_breakage.rs:4  * Doc comment for foo
rustdoc_breakage.rs:5  */
rustdoc_breakage.rs:6 // fn foo() {

I unwittingly ran into this a few weeks ago, and I've only just figured out the cause. It's very confounding if you have no idea what to look for. I would have thought that above all, the rule that comments should be ignored at compile time should be sacrosanct. If at all possible, the error should occur in rustdoc, not rustc.

[brson]

This is confusing behavior.

At the time we were hoping that it would be useful to know at compile time that your rustdoc didn't actually apply to anything. It has helped me a few times, particularly when I use an outer rustdoc at the top of a file, like /** */, but I should be using /*! */.

I agree though that it would be better for this to be a rustdoc error instead of a rustc error, but there are complications.

The reason it's like this is because rustdocs are actually discovered in the lexer, and converted to attributes so that the parser can associate them with items (or whatever) just like any attribute. Otherwise you have to have some heuristic that later extracts the doc comments and tries to associate them with code.

One very nice thing that parsing rustdocs into attributes allows us to do is put the docs directly into the crate metadata. In theory we should be able to extract docs from existing, compiled crates, and also get docs at runtime. If we stopped parsing rustdocs at compile time we would lose that property.

One possibility is to put a flag on the lexer to control whether it extracts docs. Under normal compilation it would ignore them, but rustdoc would lex the docs. In the future, when it is actually useful, crates could add a #[embed_docs] attribute to turn on doc lexing.

@nikomatsakis has expressed opinions about this before.

[brson]

We could also just try to improve the error messages.

[Dretch]

@brson

Otherwise you have to have some heuristic that later extracts the doc comments and tries to associate them with code.

Would this be so bad?

The parser could intercept DOC_COMMENT tokens from the lexer and push them onto some list for later processing by rustdoc.

The heuristic would be to simply look for the following/preceding (for outer/inner comments) item based on character position in the file. There might be some special rules to allow things like

fn a(); /// doc comment on same line.

Rustdoc could then emit error messages like:

failed to find associated item for doc-comment at line:col ....

[brson]

@Dretch I am not sure whether it would be bad or not. It is harder. If we went in that direction we should remove doc comments from the lexer. We already have code that can extract all comments from source files for the pretty printer to use, so rustdoc could just dig through those for doc comments.

The big win we could get from that approach would be to remove 'inner doc comments' that use !, instead just making a guess based on the position of the comment and surrounding context about what the comment applies to. I do think this is how most people expect doc comments to work.

[brendanzab]

Have you guys also considered a doxygen-style ///< ... or /**< ... */ for trailing doc comments that are put before the preceding item? This very useful in my case.

[brson]

@bjz agreed that it's useful. The reason we don't have them is because they don't fit the attribute model of either being 'outside' (and before) the thing it applies to or 'inside'.

fn foo(
  #[outer_attribute_can_go_here]
  bar: baz
  // no attribute can go here
) { }

[brson]

Switching to the heuristic model would of course make ///< work.

[brson]

Oh, also I'm not sure if function arguments actually accept attributes like my example indicates.

[brendanzab]

Hah, I just thought of this:

fn generic_function
<
    T,      ///< Something
    U       ///< Something else...
> (
    a: T,   ///< An argument
    b: U    ///< Another argument
) -> U {
    ...
}

struct Foo {
    a: A,    ///< blah
    b: B,    ///< blah blah
}

Might get a little unreadable though :P

Maybe rustdoc could give an error here?

/// blah
const foo: int = 0; ///< blah
const bar: int = 1; ///< blah

'Conflicting doc comments at line 1 and 2' or something.

Anyway, I'm not the one implementing this, and it looks pretty complex to figure out. But yeah, I can dream... :)

[brendanzab]

Oh, and another thing. Do you currently do an error for this?

/**
 * ...
 */
/// ...
fn blah() { }