Minor doc updates

docs/api/core_block_tokens.rst

@@ -28,30 +28,31 @@ These block tokens are defined in the
            ======
 
     * - Paragraph
-      - General inline text
+      - General block of text
       - .. code-block:: md
 
            any *text*
 
     * - Quote
-      - quoted text
+      - quoted block of text
       - .. code-block:: md
 
            > this is a quote
 
     * - BlockCode
       - indented text (4 spaces or a tab)
       - .. code-block:: md
+           :name: blockcode
 
-           included as literal *text*
+               included as literal
 
     * - CodeFence
       - enclosed in 3 or more backticks with an optional language name
       - .. code-block:: md
 
-           .. code-block:: python
-
-              print('this is python')
+           ```python
+           print('this is python')
+           ```
 
     * - ThematicBreak
       - Creates a horizontal line in the output
@@ -64,7 +65,7 @@ These block tokens are defined in the
       - .. code-block:: md
 
            - item
-           - nested item
+             - nested item
            1. numbered item
 
     * - LinkDefinition

docs/api/core_span_tokens.rst

@@ -14,7 +14,7 @@ These span tokens are defined in the
       - Description
       - Example
     * - RawText
-      - any text
+      - any inline text
       - .. code-block:: md
 
            any text
@@ -53,13 +53,15 @@ These span tokens are defined in the
       - link that is shown in final output
       - .. code-block:: md
 
-           <http://www.google.com>
+           <https://www.google.com>
 
     * - Link
-      - Reference ``LinkDefinitions``
+      - Reference a target or :py:class:`~mistletoe.block_tokens.LinkDefinition`
       - .. code-block:: md
 
-           [text](target "title") or [text][key]
+           [text](target "title") or
+           [text][key] or
+           [key]
 
     * - Image
       - link to an image