Change handling of doc comments to warn when mis-parsed, not error.

[brson]

Now that we've implemented doc comments as attributes I am doubtful that it was the correct thing to do. There are a lot of positions where attributes aren't valid and now the parser rejects things like:

let x = y; //// xy

I was planning putting some smarts into the lexer to detect four slashes and not consider those doc attributes, but then patrick checked in some code like ///< comment which was rejected.

Comments not being treated as whitespace is weird.

[brson]

On second thought, I kind of want to see how the current arrangement works before changing it. There is some amount of value in catching incorrect doc comments, which is sort of what happened with the ///< comment.

[brson]

I've run into another case where sections were formatted like /****** Some Stuff ******/. It failed to compile with an error that wouldn't lead you to expect that the comment was incorrect.

[catamorphism]

Nominating for "maturity #4 - well covered"

[graydon]

It represents a potential backwards incompatibility, so belongs on the backward compatible maturity milestone (or closed as wontfix)

[emberian]

I don't see how this could be a backwards incompatibility. Fixing the error to be better is no problem and allowing this behavior wouldn't break any valid code.

Nominating for production ready.

[emberian]

Example errors:

foo.rs:6:24: 7:0 error: expected item after attributes
foo.rs:6     let x = Foo{x: 5u}; /// bar
foo.rs:7 }

foo.rs:5:0: 6:0 error: expected item after attributes
foo.rs:5 /****** Some Stuff ******/
foo.rs:6     let x = Foo{x: 5u};

Which honestly isn't that bad but it's not good either.

[huonw]

Triage visit; all the examples reproduce.

I'm absorbing #4106 into this bug (#4106 has a lot of historical discussion).

[pzol]

Visiting for triage, still broken.

[mikedilger]

First off, I LOVE you guys and am so glad rust is happening. But I'm frustrated today about this issue. I'm still very new to rust, and it took me hours to figure out the problem, mostly because the error message I get is very misdirecting:

  mymod.js:6:3: 6:4 error: an inner attribute is not permitted in this context
  mymod.js:6 #![feature(phase)]

I strongly recommend a better error message, if at all possible, so you don't lose new people to the community.

My code was something like this:

/**
 * My mod
 */

// For log related macros:
#![feature(phase)]
#[phase(syntax, link)] extern crate log;

fn main() {
  error!("We have logging!");
}