From 4850ceaa192dc482f7c34c96713cd0c53b6722df Mon Sep 17 00:00:00 2001
From: Jaapio <jaap@ijaap.nl>
Date: Fri, 2 Feb 2024 13:39:53 +0100
Subject: [PATCH] Add reference docs

---
 .../TextRoles/AbbreviationTextRole.php                |  9 +++++++++
 .../TextRoles/DocReferenceTextRole.php                |  9 +++++++++
 .../TextRoles/GenericLinkProvider.php                 |  9 +++++++++
 src/RestructuredText/TextRoles/LiteralTextRole.php    | 11 +++++++++++
 src/RestructuredText/TextRoles/MathTextRole.php       | 11 +++++++++++
 src/RestructuredText/TextRoles/SpanTextRole.php       | 11 -----------
 6 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/src/RestructuredText/TextRoles/AbbreviationTextRole.php b/src/RestructuredText/TextRoles/AbbreviationTextRole.php
index c1c6d8f..a32e295 100644
--- a/src/RestructuredText/TextRoles/AbbreviationTextRole.php
+++ b/src/RestructuredText/TextRoles/AbbreviationTextRole.php
@@ -21,6 +21,15 @@
 use function preg_match;
 use function trim;
 
+/**
+ * Role to create an abbreviation.
+ *
+ * Example:
+ *
+ * ```rest
+ * :abbreviation:`term (some term definition)`
+ * ```
+ */
 final class AbbreviationTextRole extends BaseTextRole
 {
     protected string $name = 'abbreviation';
diff --git a/src/RestructuredText/TextRoles/DocReferenceTextRole.php b/src/RestructuredText/TextRoles/DocReferenceTextRole.php
index 6d80ba2..7c0370d 100644
--- a/src/RestructuredText/TextRoles/DocReferenceTextRole.php
+++ b/src/RestructuredText/TextRoles/DocReferenceTextRole.php
@@ -17,6 +17,15 @@
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
 use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
 
+/**
+ * Role to create a reference to a document.
+ *
+ * Example:
+ *
+ * ```rest
+ * :doc:`doc/index`
+ * ```
+ */
 final class DocReferenceTextRole extends AbstractReferenceTextRole
 {
     final public const NAME = 'doc';
diff --git a/src/RestructuredText/TextRoles/GenericLinkProvider.php b/src/RestructuredText/TextRoles/GenericLinkProvider.php
index fe69afa..df8f096 100644
--- a/src/RestructuredText/TextRoles/GenericLinkProvider.php
+++ b/src/RestructuredText/TextRoles/GenericLinkProvider.php
@@ -15,6 +15,15 @@
 
 use phpDocumentor\Guides\Nodes\SectionNode;
 
+/**
+ *  Role to create references to link targets.
+ *
+ *  Example:
+ *
+ * ```rest
+ *  :ref:`label`
+ * ```
+ */
 final class GenericLinkProvider
 {
     /** @var array<string, string> */
diff --git a/src/RestructuredText/TextRoles/LiteralTextRole.php b/src/RestructuredText/TextRoles/LiteralTextRole.php
index a19e2ff..82732a6 100644
--- a/src/RestructuredText/TextRoles/LiteralTextRole.php
+++ b/src/RestructuredText/TextRoles/LiteralTextRole.php
@@ -16,6 +16,17 @@
 use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 
+/**
+ * Role to create a literal block.
+ *
+ * A literal block is a block of text that is displayed as-is, without any formatting.
+ *
+ * Example:
+ *
+ * ```rest
+ * :literal:`code`
+ * ```
+ */
 final class LiteralTextRole extends BaseTextRole
 {
     protected string $name = 'literal';
diff --git a/src/RestructuredText/TextRoles/MathTextRole.php b/src/RestructuredText/TextRoles/MathTextRole.php
index 3522ea3..e92c5a7 100644
--- a/src/RestructuredText/TextRoles/MathTextRole.php
+++ b/src/RestructuredText/TextRoles/MathTextRole.php
@@ -16,6 +16,17 @@
 use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 
+/**
+ * Role to create a math block.
+ *
+ * A math block is a block of text that is displayed as-is, without any formatting.
+ *
+ * Example:
+ *
+ * ```rest
+ * :math:`code`
+ * ```
+ */
 final class MathTextRole extends BaseTextRole
 {
     protected string $name = 'math';
diff --git a/src/RestructuredText/TextRoles/SpanTextRole.php b/src/RestructuredText/TextRoles/SpanTextRole.php
index 81bf94d..ce8d56f 100644
--- a/src/RestructuredText/TextRoles/SpanTextRole.php
+++ b/src/RestructuredText/TextRoles/SpanTextRole.php
@@ -16,17 +16,6 @@
 use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 
-/**
- * This text role is extended by custom text roles that do not feature a base text role:
- *
- * ```
- * .. role:: custom
- *    :class: special
- *
- *    :custom:`interpreted text`
- *
- * ```
- */
 final class SpanTextRole extends BaseTextRole
 {
     protected string $name = 'span';