Add reference docs

Author: jaapio

docs/about.rst

@@ -10,6 +10,19 @@ You can also :doc:`add your own custom text roles </extension/text-roles>`.
 
 Currently the following text roles are implemented:
 
+.. phpdoc:class-list:: [?(@.interfacesIncludingInherited contains "\phpDocumentor\Guides\RestructuredText\TextRoles\TextRole")]
+
+   .. phpdoc:name::
+      :title: true
+      :level: 2
+
+   .. phpdoc:summary::
+   .. phpdoc:description::
+
+
+Examples
+========
+
 :ref:`Reference somewhere <basic-text-role>`
 
 :doc:`Reference to document </extension/text-roles>`

docs/reference/restructuredtext/text-roles.rst

@@ -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';

packages/guides-restructured-text/src/RestructuredText/TextRoles/AbbreviationTextRole.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';

packages/guides-restructured-text/src/RestructuredText/TextRoles/DocReferenceTextRole.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> */

packages/guides-restructured-text/src/RestructuredText/TextRoles/GenericLinkProvider.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';

packages/guides-restructured-text/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 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';

packages/guides-restructured-text/src/RestructuredText/TextRoles/MathTextRole.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';