Add reference docs

phpDocumentor · Feb 18, 2024 · 4850cea · 4850cea
1 parent 2344d8e
commit 4850cea
Show file tree

Hide file tree

Showing 6 changed files with 49 additions and 11 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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';