diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index 7e4c2ba3be875..8683689bbbe24 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -636,10 +636,10 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
 
 generate_pattern_iterators! {
     forward:
-        #[doc="Created with the method `.split()`."]
+        /// Created with the method `.split()`.
         struct Split;
     reverse:
-        #[doc="Created with the method `.rsplit()`."]
+        /// Created with the method `.rsplit()`.
         struct RSplit;
     stability:
         #[stable(feature = "rust1", since = "1.0.0")]
@@ -650,10 +650,10 @@ generate_pattern_iterators! {
 
 generate_pattern_iterators! {
     forward:
-        #[doc="Created with the method `.split_terminator()`."]
+        /// Created with the method `.split_terminator()`.
         struct SplitTerminator;
     reverse:
-        #[doc="Created with the method `.rsplit_terminator()`."]
+        /// Created with the method `.rsplit_terminator()`.
         struct RSplitTerminator;
     stability:
         #[stable(feature = "rust1", since = "1.0.0")]
@@ -696,10 +696,10 @@ impl<'a, P: Pattern<'a>> SplitNInternal<'a, P> {
 
 generate_pattern_iterators! {
     forward:
-        #[doc="Created with the method `.splitn()`."]
+        /// Created with the method `.splitn()`.
         struct SplitN;
     reverse:
-        #[doc="Created with the method `.rsplitn()`."]
+        /// Created with the method `.rsplitn()`.
         struct RSplitN;
     stability:
         #[stable(feature = "rust1", since = "1.0.0")]
@@ -730,10 +730,10 @@ impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> {
 
 generate_pattern_iterators! {
     forward:
-        #[doc="Created with the method `.match_indices()`."]
+        /// Created with the method `.match_indices()`.
         struct MatchIndices;
     reverse:
-        #[doc="Created with the method `.rmatch_indices()`."]
+        /// Created with the method `.rmatch_indices()`.
         struct RMatchIndices;
     stability:
         #[unstable(feature = "str_match_indices",
@@ -771,10 +771,10 @@ impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> {
 
 generate_pattern_iterators! {
     forward:
-        #[doc="Created with the method `.matches()`."]
+        /// Created with the method `.matches()`.
         struct Matches;
     reverse:
-        #[doc="Created with the method `.rmatches()`."]
+        /// Created with the method `.rmatches()`.
         struct RMatches;
     stability:
         #[stable(feature = "str_matches", since = "1.2.0")]
diff --git a/src/libsyntax/ast.rs b/src/libsyntax/ast.rs
index a944acad84df1..a0059d33bed84 100644
--- a/src/libsyntax/ast.rs
+++ b/src/libsyntax/ast.rs
@@ -63,6 +63,7 @@ use owned_slice::OwnedSlice;
 use parse::token::{InternedString, str_to_ident};
 use parse::token;
 use parse::lexer;
+use parse::lexer::comments::{doc_comment_style, strip_doc_comment_decoration};
 use print::pprust;
 use ptr::P;
 
@@ -1079,7 +1080,12 @@ pub enum TokenTree {
 impl TokenTree {
     pub fn len(&self) -> usize {
         match *self {
-            TtToken(_, token::DocComment(_)) => 2,
+            TtToken(_, token::DocComment(name)) => {
+                match doc_comment_style(name.as_str()) {
+                    AttrOuter => 2,
+                    AttrInner => 3
+                }
+            }
             TtToken(_, token::SpecialVarNt(..)) => 2,
             TtToken(_, token::MatchNt(..)) => 3,
             TtDelimited(_, ref delimed) => {
@@ -1097,14 +1103,20 @@ impl TokenTree {
             (&TtToken(sp, token::DocComment(_)), 0) => {
                 TtToken(sp, token::Pound)
             }
-            (&TtToken(sp, token::DocComment(name)), 1) => {
+            (&TtToken(sp, token::DocComment(name)), 1)
+            if doc_comment_style(name.as_str()) == AttrInner => {
+                TtToken(sp, token::Not)
+            }
+            (&TtToken(sp, token::DocComment(name)), _) => {
+                let stripped = strip_doc_comment_decoration(name.as_str());
                 TtDelimited(sp, Rc::new(Delimited {
                     delim: token::Bracket,
                     open_span: sp,
                     tts: vec![TtToken(sp, token::Ident(token::str_to_ident("doc"),
                                                        token::Plain)),
                               TtToken(sp, token::Eq),
-                              TtToken(sp, token::Literal(token::StrRaw(name, 0), None))],
+                              TtToken(sp, token::Literal(
+                                  token::StrRaw(token::intern(&stripped), 0), None))],
                     close_span: sp,
                 }))
             }
diff --git a/src/test/parse-fail/macro-doc-comments-1.rs b/src/test/parse-fail/macro-doc-comments-1.rs
new file mode 100644
index 0000000000000..03bcef4fa5ee0
--- /dev/null
+++ b/src/test/parse-fail/macro-doc-comments-1.rs
@@ -0,0 +1,19 @@
+// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+macro_rules! outer {
+    (#[$outer:meta]) => ()
+}
+
+outer! {
+    //! Inner
+} //~^ ERROR no rules expected the token `!`
+
+fn main() { }
diff --git a/src/test/parse-fail/macro-doc-comments-2.rs b/src/test/parse-fail/macro-doc-comments-2.rs
new file mode 100644
index 0000000000000..a1b112c29b6e0
--- /dev/null
+++ b/src/test/parse-fail/macro-doc-comments-2.rs
@@ -0,0 +1,19 @@
+// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+macro_rules! inner {
+    (#![$inner:meta]) => ()
+}
+
+inner! {
+    /// Outer
+} //~^ ERROR no rules expected the token `[`
+
+fn main() { }
diff --git a/src/test/run-pass/macro-doc-comments.rs b/src/test/run-pass/macro-doc-comments.rs
new file mode 100644
index 0000000000000..506813df5b374
--- /dev/null
+++ b/src/test/run-pass/macro-doc-comments.rs
@@ -0,0 +1,33 @@
+// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+macro_rules! doc {
+    (
+        $(#[$outer:meta])*
+        mod $i:ident {
+            $(#![$inner:meta])*
+        }
+    ) =>
+    (
+        $(#[$outer])*
+        pub mod $i {
+            $(#![$inner])*
+        }
+    )
+}
+
+doc! {
+    /// Outer doc
+    mod Foo {
+        //! Inner doc
+    }
+}
+
+fn main() { }
diff --git a/src/test/rustdoc/issue-23812.rs b/src/test/rustdoc/issue-23812.rs
new file mode 100644
index 0000000000000..37f6749694c40
--- /dev/null
+++ b/src/test/rustdoc/issue-23812.rs
@@ -0,0 +1,46 @@
+// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+macro_rules! doc {
+    (#[$outer:meta] mod $i:ident { #![$inner:meta] }) =>
+    (
+        #[$outer]
+        pub mod $i {
+            #![$inner]
+        }
+    )
+}
+
+doc! {
+    /// Outer comment
+    mod Foo {
+        //! Inner comment
+    }
+}
+
+// @has issue_23812/Foo/index.html
+// @has - 'Outer comment'
+// @!has - '/// Outer comment'
+// @has - 'Inner comment'
+// @!has - '//! Inner comment'
+
+
+doc! {
+    /** Outer block comment */
+    mod Bar {
+        /*! Inner block comment */
+    }
+}
+
+// @has issue_23812/Bar/index.html
+// @has - 'Outer block comment'
+// @!has - '/** Outer block comment */'
+// @has - 'Inner block comment'
+// @!has - '/*! Inner block comment */'