human readable descriptions for Markdown Block Directive errors

Author: tayloraswift

Sources/MarkdownSemantics/AST/Markdown.BlockDirectiveArgumentTypeError.swift

@@ -4,5 +4,16 @@ extension Markdown
         where Option:BlockDirectiveOption
     {
         let option:Option
+        let value:String
+    }
+}
+extension Markdown.BlockDirectiveArgumentTypeError:CustomStringConvertible
+{
+    var description:String
+    {
+        """
+        could not convert argument '\(self.value)' for option '\(self.option)' to expected \
+        type '\(Value.self)'
+        """
     }
 }

Sources/MarkdownSemantics/AST/Markdown.BlockDirectiveDuplicateOptionError.swift

@@ -5,3 +5,10 @@ extension Markdown
         let option:Option
     }
 }
+extension Markdown.BlockDirectiveDuplicateOptionError:CustomStringConvertible
+{
+    var description:String
+    {
+        "duplicate option '\(self.option.rawValue)'"
+    }
+}

Sources/MarkdownSemantics/AST/Markdown.BlockDirectiveOption (ext).swift

@@ -8,7 +8,9 @@ extension Markdown.BlockDirectiveOption
         let value:Value = .init(rawValue: value.string)
         else
         {
-            throw Markdown.BlockDirectiveArgumentTypeError<Self, Value>.init(option: self)
+            throw Markdown.BlockDirectiveArgumentTypeError<Self, Value>.init(
+                option: self,
+                value: value.string)
         }
 
         return value
@@ -22,7 +24,9 @@ extension Markdown.BlockDirectiveOption
         let value:Value = .init(value.string)
         else
         {
-            throw Markdown.BlockDirectiveArgumentTypeError<Self, Value>.init(option: self)
+            throw Markdown.BlockDirectiveArgumentTypeError<Self, Value>.init(
+                option: self,
+                value: value.string)
         }
 
         return value

Sources/MarkdownSemantics/AST/Media/Markdown.BlockCodeFragment.PathError.swift

@@ -6,3 +6,23 @@ extension Markdown.BlockCodeFragment
         case format(String)
     }
 }
+extension Markdown.BlockCodeFragment.PathError:CustomStringConvertible
+{
+    var description:String
+    {
+        switch self
+        {
+        case .directory(let path):
+            """
+            the legacy 'path' syntax requires the second path component to be 'Snippets', \
+            found '\(path)'
+            """
+
+        case .format(let path):
+            """
+            the legacy 'path' syntax requires a path of the form 'Package/Snippets/Name', \
+            found '\(path)'
+            """
+        }
+    }
+}

Sources/MarkdownSemantics/AST/Media/Markdown.BlockCodeFragment.ReferenceError.swift

@@ -6,3 +6,28 @@ extension Markdown.BlockCodeFragment
         case slice(undefined:String, available:[String])
     }
 }
+extension Markdown.BlockCodeFragment.ReferenceError:CustomStringConvertible
+{
+    var description:String
+    {
+        switch self
+        {
+        case .snippet(nil, let available):
+            """
+            no snippet 'id' or 'path' is defined, available snippets are: \
+            \(available.lazy.map { "'\($0)'" } .joined(separator: ", "))
+            """
+        case .snippet(let undefined?, let available):
+            """
+            no such snippet '\(undefined)' exists in this package, available snippets are: \
+            \(available.lazy.map { "'\($0)'" } .joined(separator: ", "))
+            """
+
+        case .slice(let undefined, let available):
+            """
+            snippet does not contain a slice named '\(undefined)', available slices: \
+            \(available.lazy.map { "'\($0)'" } .joined(separator: ", "))
+            """
+        }
+    }
+}

Sources/MarkdownSemantics/AST/Media/Markdown.BlockCodeFragment.swift

@@ -101,14 +101,14 @@ extension Markdown.BlockCodeFragment:Markdown.BlockDirectiveType
             //  OK for the path to contain additional intermediate path components, which
             //  are just as irrelevant as the package name, because snippet names are
             //  unique within a package.
-            guard
-            case "Snippets" = value[value.index(after: i)...].prefix(while: { $0 != "/" })
-            else
+            switch value[value.index(after: i)...].prefix(while: { $0 != "/" })
             {
-                throw PathError.directory(value)
-            }
+            case "Snippets":
+                self.snippet = String.init(value[value.index(after: j)...])
 
-            self.snippet = String.init(value[value.index(after: j)...])
+            case let invalid:
+                throw PathError.directory(String.init(invalid))
+            }
         }
     }
 }

Sources/MarkdownSemantics/AST/Media/Markdown.BlockCodeReference.SemanticError.swift

@@ -5,3 +5,16 @@ extension Markdown.BlockCodeReference
         case resetContradictsBase
     }
 }
+extension Markdown.BlockCodeReference.SemanticError:CustomStringConvertible
+{
+    var description:String
+    {
+        switch self
+        {
+        case .resetContradictsBase:
+            """
+            'reset' cannot be used with 'base' (a.k.a. 'previousFile')
+            """
+        }
+    }
+}

Sources/MarkdownSemantics/AST/Media/Markdown.BlockLeaf.StructuralError.swift

@@ -5,3 +5,16 @@ extension Markdown.BlockLeaf
         case childUnexpected
     }
 }
+extension Markdown.BlockLeaf.StructuralError:CustomStringConvertible
+{
+    var description:String
+    {
+        switch self
+        {
+        case .childUnexpected:
+            """
+            block directive of this type cannot contain child blocks
+            """
+        }
+    }
+}

Sources/MarkdownSemantics/AST/Tutorials/Markdown.BlockArticle.StructuralError.swift

@@ -5,3 +5,16 @@ extension Markdown.BlockArticle
         case intro(type:Markdown.BlockElement.Type)
     }
 }
+extension Markdown.BlockArticle.StructuralError:CustomStringConvertible
+{
+    var description:String
+    {
+        switch self
+        {
+        case .intro(let type):
+            """
+            the first block in an article should be an '@Intro', found '\(type)'
+            """
+        }
+    }
+}

Sources/MarkdownSemantics/AST/Tutorials/Markdown.BlockTopicReference.TargetError.swift

@@ -5,3 +5,16 @@ extension Markdown.BlockTopicReference
         case doclink(String)
     }
 }
+extension Markdown.BlockTopicReference.TargetError:CustomStringConvertible
+{
+    var description:String
+    {
+        switch self
+        {
+        case .doclink(let link):
+            """
+            could not parse documentation link '\(link)'
+            """
+        }
+    }
+}