1use serde::Deserialize;
2use serde::Serialize;
3
4use mago_span::HasSpan;
5use mago_span::Span;
6
7#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
8pub enum ParseError {
9 InvalidTrivia(Span),
10 UnclosedInlineTag(Span),
11 UnclosedInlineCode(Span),
12 UnclosedCodeBlock(Span),
13 InvalidTagName(Span),
14 MalformedCodeBlock(Span),
15 InvalidComment(Span),
16 ExpectedLine(Span),
17 InvalidTypeTag(Span, String),
18 InvalidImportTypeTag(Span, String),
19 InvalidTemplateTag(Span, String),
20 InvalidParameterTag(Span, String),
21 InvalidReturnTag(Span, String),
22 InvalidPropertyTag(Span, String),
23 InvalidMethodTag(Span, String),
24 InvalidThrowsTag(Span, String),
25 InvalidAssertionTag(Span, String),
26 InvalidVarTag(Span, String),
27 InvalidWhereTag(Span, String),
28 InvalidParameterOutTag(Span, String),
29}
30
31impl HasSpan for ParseError {
32 fn span(&self) -> Span {
33 match self {
34 ParseError::InvalidTrivia(span)
35 | ParseError::UnclosedInlineTag(span)
36 | ParseError::UnclosedInlineCode(span)
37 | ParseError::UnclosedCodeBlock(span)
38 | ParseError::InvalidTagName(span)
39 | ParseError::MalformedCodeBlock(span)
40 | ParseError::InvalidComment(span)
41 | ParseError::ExpectedLine(span)
42 | ParseError::InvalidTypeTag(span, _)
43 | ParseError::InvalidImportTypeTag(span, _)
44 | ParseError::InvalidTemplateTag(span, _)
45 | ParseError::InvalidParameterTag(span, _)
46 | ParseError::InvalidReturnTag(span, _)
47 | ParseError::InvalidPropertyTag(span, _)
48 | ParseError::InvalidMethodTag(span, _)
49 | ParseError::InvalidThrowsTag(span, _)
50 | ParseError::InvalidAssertionTag(span, _)
51 | ParseError::InvalidVarTag(span, _)
52 | ParseError::InvalidWhereTag(span, _)
53 | ParseError::InvalidParameterOutTag(span, _) => *span,
54 }
55 }
56}
57
58impl std::error::Error for ParseError {}
59
60impl std::fmt::Display for ParseError {
61 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
62 match self {
63 ParseError::InvalidTrivia(_) | ParseError::InvalidComment(_) => {
64 write!(f, "Invalid docblock format")
65 }
66 ParseError::UnclosedInlineTag(_) => write!(f, "Unclosed inline tag"),
67 ParseError::UnclosedInlineCode(_) => write!(f, "Unclosed inline code"),
68 ParseError::UnclosedCodeBlock(_) => write!(f, "Unclosed code block"),
69 ParseError::InvalidTagName(_) => write!(f, "Invalid tag name"),
70 ParseError::MalformedCodeBlock(_) => write!(f, "Malformed code block"),
71 ParseError::ExpectedLine(_) => write!(f, "Unexpected end of docblock"),
72 ParseError::InvalidTypeTag(_, msg) => write!(f, "{msg}"),
73 ParseError::InvalidImportTypeTag(_, msg) => write!(f, "{msg}"),
74 ParseError::InvalidTemplateTag(_, msg) => write!(f, "{msg}"),
75 ParseError::InvalidParameterTag(_, msg) => write!(f, "{msg}"),
76 ParseError::InvalidReturnTag(_, msg) => write!(f, "{msg}"),
77 ParseError::InvalidPropertyTag(_, msg) => write!(f, "{msg}"),
78 ParseError::InvalidMethodTag(_, msg) => write!(f, "{msg}"),
79 ParseError::InvalidThrowsTag(_, msg) => write!(f, "{msg}"),
80 ParseError::InvalidAssertionTag(_, msg) => write!(f, "{msg}"),
81 ParseError::InvalidVarTag(_, msg) => write!(f, "{msg}"),
82 ParseError::InvalidWhereTag(_, msg) => write!(f, "{msg}"),
83 ParseError::InvalidParameterOutTag(_, msg) => write!(f, "{msg}"),
84 }
85 }
86}
87
88impl ParseError {
89 #[must_use]
90 pub fn note(&self) -> String {
91 match self {
92 ParseError::InvalidTrivia(_) | ParseError::InvalidComment(_) => {
93 "Docblocks must start with `/**` and end with `*/`.".to_string()
94 }
95 ParseError::UnclosedInlineTag(_) => {
96 "Inline tags like `{@see}` must be closed with a matching `}`.".to_string()
97 }
98 ParseError::UnclosedInlineCode(_) => {
99 "Inline code snippets must be enclosed in matching backticks (`).".to_string()
100 }
101 ParseError::UnclosedCodeBlock(_) => {
102 "Multi-line code blocks must be terminated with a closing ```.".to_string()
103 }
104 ParseError::InvalidTagName(_) => {
105 "Docblock tag names must contain only letters, numbers, underscores, hyphens, colons, or backslashes."
106 .to_string()
107 }
108 ParseError::MalformedCodeBlock(_) => {
109 "A code block must start with ``` optionally followed by a language identifier.".to_string()
110 }
111 ParseError::ExpectedLine(_) => {
112 "A tag or description was expected here, but the docblock ended prematurely.".to_string()
113 }
114 ParseError::InvalidTypeTag(_, _) => "Type alias must have name followed by type definition".to_string(),
115 ParseError::InvalidImportTypeTag(_, _) => {
116 "Import must have type name, `from` keyword, and class name".to_string()
117 }
118 ParseError::InvalidTemplateTag(_, _) => "Template must have parameter name".to_string(),
119 ParseError::InvalidParameterTag(_, _) => "Parameter must have type followed by variable name".to_string(),
120 ParseError::InvalidReturnTag(_, _) => "Return must have valid type".to_string(),
121 ParseError::InvalidPropertyTag(_, _) => "Property must have type and/or variable name".to_string(),
122 ParseError::InvalidMethodTag(_, _) => "Method must have return type, name, and parameter list".to_string(),
123 ParseError::InvalidThrowsTag(_, _) => "Throws must have exception type".to_string(),
124 ParseError::InvalidAssertionTag(_, _) => "Assertion must have type followed by variable name".to_string(),
125 ParseError::InvalidVarTag(_, _) => "Variable must have type".to_string(),
126 ParseError::InvalidWhereTag(_, _) => {
127 "Template constraint must have parameter name, `is` or `:`, and type".to_string()
128 }
129 ParseError::InvalidParameterOutTag(_, _) => {
130 "Output parameter must have type followed by variable name".to_string()
131 }
132 }
133 }
134
135 #[must_use]
136 pub fn help(&self) -> String {
137 match self {
138 ParseError::UnclosedInlineTag(_) => "Add a closing `}` to complete the inline tag.".to_string(),
139 ParseError::UnclosedInlineCode(_) => {
140 "Add a closing backtick ` ` ` to terminate the inline code.".to_string()
141 }
142 ParseError::UnclosedCodeBlock(_) => "Add a closing ``` to terminate the code block.".to_string(),
143 ParseError::InvalidTagName(_) => {
144 "Correct the tag name to use only valid characters (e.g., `@my-custom-tag`).".to_string()
145 }
146 ParseError::InvalidTypeTag(_, _) => {
147 "Add type definition after alias name (can span multiple lines)".to_string()
148 }
149 ParseError::InvalidImportTypeTag(_, _) => {
150 "Ensure type name is followed by `from` and a valid class name".to_string()
151 }
152 ParseError::InvalidTemplateTag(_, _) => "Provide a valid template parameter name".to_string(),
153 ParseError::InvalidParameterTag(_, _) => {
154 "Ensure type is followed by a valid parameter name (e.g., `$param`)".to_string()
155 }
156 ParseError::InvalidReturnTag(_, _) => "Provide a valid return type".to_string(),
157 ParseError::InvalidPropertyTag(_, _) => {
158 "Ensure property has valid type and/or variable name (e.g., `$prop`)".to_string()
159 }
160 ParseError::InvalidMethodTag(_, _) => "Provide return type, method name, and parameter list".to_string(),
161 ParseError::InvalidThrowsTag(_, _) => "Provide a valid exception class name".to_string(),
162 ParseError::InvalidAssertionTag(_, _) => {
163 "Ensure type is followed by a valid variable name (e.g., `$var`)".to_string()
164 }
165 ParseError::InvalidVarTag(_, _) => "Provide a valid type for the variable".to_string(),
166 ParseError::InvalidWhereTag(_, _) => {
167 "Ensure template name is followed by `is` or `:` and a type".to_string()
168 }
169 ParseError::InvalidParameterOutTag(_, _) => {
170 "Ensure type is followed by a valid parameter name (e.g., `$param`)".to_string()
171 }
172 _ => "Review the docblock syntax to ensure it is correctly formatted.".to_string(),
173 }
174 }
175}