feat: better error message for misplaced doc comments (#5990)

# Description

## Problem

Resolves #5989

## Summary

Whenever there's a parsing error and we find a doc comment it means it's
a misplaced doc comment.

## Additional Context


## Documentation

Check one:
- [x] No documentation needed.
- [ ] Documentation included in this PR.
- [ ] **[For Experimental Features]** Documentation to be submitted in a
separate PR.

# PR Checklist

- [x] I have tested the changes locally.
- [x] I have formatted the changes with [Prettier](https://prettier.io/)
and/or `cargo fmt` on default settings.

compiler/noirc_frontend/src/parser/errors.rs

@@ -1,6 +1,7 @@
 use crate::ast::{Expression, IntegerBitSize};
 use crate::lexer::errors::LexerErrorKind;
 use crate::lexer::token::Token;
+use crate::token::TokenKind;
 use small_ord_set::SmallOrdSet;
 use thiserror::Error;
 
@@ -211,8 +212,17 @@ impl<'a> From<&'a ParserError> for Diagnostic {
                 other => Diagnostic::simple_error(format!("{other}"), String::new(), error.span),
             },
             None => {
-                let primary = error.to_string();
-                Diagnostic::simple_error(primary, String::new(), error.span)
+                if matches!(
+                    error.found.kind(),
+                    TokenKind::InnerDocComment | TokenKind::OuterDocComment
+                ) {
+                    let primary = "This doc comment doesn't document anything".to_string();
+                    let secondary = "Consider changing it to a regular `//` comment".to_string();
+                    Diagnostic::simple_error(primary, secondary, error.span)
+                } else {
+                    let primary = error.to_string();
+                    Diagnostic::simple_error(primary, String::new(), error.span)
+                }
             }
         }
     }