rdoc 7.0.3 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e115c57c1541a612613ea80a869ce964b13aee43badba6c75bae66aa70495e29
-  data.tar.gz: 5a0dfd61dc9a5116612d939f3d94197fe687667cd8185d00983afb3fea38aade
+  metadata.gz: c14913bad669603f9b9662966297c2e33b45af4500c9cd71bbff067da334ee1a
+  data.tar.gz: 4e40f1f5b579891945cc7e365bf3977863eb9236eb9af872d870cb46317d191b
 SHA512:
-  metadata.gz: fc7d789798d547865d5205eafbb6b8db9b5b16bc422c5fba3658952a8568248eda44aba606c1c1cac335af38babdf18bf4a2aa56f1c7189fe894858e154c9353
-  data.tar.gz: da731f564307246734edefbc271577d434b3d4527d865cd2c6575db5dce5d36caab97925204bacbb1a2063aff4109a55db5c269829df32e5ac29163b366b8c7d
+  metadata.gz: 3aadc0477ea9dd400c1128c512352745b7835171f998c89a83a2827190a41e171d6fa5b89e5c9a27da0bab76fa5492236f7ce13d59ce64970cd414abd9da806c
+  data.tar.gz: a6949c4950b1fd69c8176330e1c6bedb4912281521f31f66d36b123e912d7fe2bf4736cfd0dae22ac8de939badd817bbd771f500bbc65f8041ab7939d43a3e14

data/README.md

@@ -60,7 +60,7 @@ You can specify the target files for document generation with `.document` file i
 
 ## Writing Documentation
 
-To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:
+To write documentation for RDoc, place a comment above the class, module, method, constant, or attribute you want documented:
 
 ```rb
 ##
@@ -80,13 +80,79 @@ class Shape
 end
 ```
 
-The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported.  You can set the default comment format for your entire project by creating a `.rdoc_options` file.  See RDoc::Options@Saved+Options for instructions on creating one.  You can also set the comment format for a single file through the `:markup:` directive, but this is only recommended if you wish to switch markup formats.  See RDoc::Markup@Other+directives.
+### Markup Formats
 
-Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing.  See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic.  See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
+RDoc supports multiple markup formats:
+
+| Format | File Extensions | Default For |
+|--------|-----------------|-------------|
+| [RDoc](doc/markup_reference/rdoc.rdoc) | `.rdoc` | `.rb`, `.c` files |
+| [Markdown](doc/markup_reference/markdown.md) | `.md` | None |
+| RD | `.rd` | None |
+| TomDoc | N/A | None |
+
+**RDoc markup** is currently the default format for Ruby and C files. However, we plan to retire it in favor of Markdown in the future.
+
+**Markdown** support is actively being improved. Once it reaches feature parity with RDoc markup, it will become the default format.
+
+For standalone documentation files, we recommend writing `.md` files instead of `.rdoc` files.
+
+**RD** and **TomDoc** are legacy formats. We highly discourage their use in new projects.
+
+### Specifying Markup Format
+
+**Per-file:** Add a `:markup:` directive at the top of a Ruby file:
+
+```ruby
+# :markup: markdown
+
+# This class uses **Markdown** for documentation.
+class MyClass
+end
+```
+
+**Per-project:** Create a `.rdoc_options` file in your project root:
+
+```yaml
+markup: markdown
+```
+
+**Command line:**
+
+```bash
+rdoc --markup markdown
+```
+
+### Feature Differences
+
+| Feature | RDoc Markup | Markdown |
+|---------|-------------|----------|
+| Headings | `= Heading` | `# Heading` |
+| Bold | `*word*` | `**word**` |
+| Italic | `_word_` | `*word*` |
+| Monospace | `+word+` | `` `word` `` |
+| Links | `{text}[url]` | `[text](url)` |
+| Code blocks | Indent 2 spaces | Fenced with ``` |
+| Cross-references | Automatic | Automatic |
+| Directives (`:nodoc:`, etc.) | Supported | Supported |
+| Tables | Not supported | Supported |
+| Strikethrough | `<del>text</del>` | `~~text~~` |
+| Footnotes | Not supported | Supported |
+
+For complete syntax documentation, see:
+
+- [RDoc Markup Reference](doc/markup_reference/rdoc.rdoc)
+- [Markdown Reference](doc/markup_reference/markdown.md)
+
+### Directives
+
+Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing. See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic. See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
 
 See RDoc::Parser::C for documenting C extensions with RDoc.
 
-To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report.  `rdoc -C1 lib` includes parameter names in the documentation coverage report.
+### Documentation Coverage
+
+To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report. `rdoc -C1 lib` includes parameter names in the documentation coverage report.
 
 ## Theme Options
 

data/doc/markup_reference/markdown.md

@@ -0,0 +1,558 @@
+# Markdown Reference
+
+This document is the comprehensive reference for Markdown support in RDoc.
+It covers all syntax, extensions, and formatting options available.
+
+For Ruby-specific features that require actual code (like cross-reference targets
+and directives that only work in Ruby comments), see RDoc::Example.
+
+## About the Examples
+
+- Examples show Markdown syntax.
+- Rendered output is shown in blockquotes where helpful.
+
+## Blocks
+
+Markdown documents consist of various block types:
+
+- [Paragraphs](#paragraphs): ordinary text blocks.
+- [Headings](#headings): section titles.
+- [Code Blocks](#code-blocks): verbatim text with syntax highlighting.
+- [Blockquotes](#blockquotes): quoted passages.
+- [Lists](#lists): bullet, numbered, and definition lists.
+- [Tables](#tables): tabular data.
+- [Horizontal Rules](#horizontal-rules): visual separators.
+
+### Paragraphs
+
+A paragraph is one or more consecutive lines of text,
+separated from other blocks by blank lines.
+
+Example:
+
+```markdown
+This is the first paragraph. It can span
+multiple lines.
+
+This is the second paragraph.
+```
+
+Single newlines within a paragraph become spaces in the output.
+
+### Headings
+
+#### ATX-Style Headings
+
+Use `#` characters at the start of a line. Levels 1-6 are supported:
+
+```markdown
+# Heading Level 1
+## Heading Level 2
+### Heading Level 3
+#### Heading Level 4
+##### Heading Level 5
+###### Heading Level 6
+```
+
+Optional closing `#` characters are allowed:
+
+```markdown
+## Heading ##
+```
+
+#### Setext-Style Headings
+
+Underline text with `=` for level 1 or `-` for level 2:
+
+```markdown
+Heading Level 1
+===============
+
+Heading Level 2
+---------------
+```
+
+### Code Blocks
+
+#### Indented Code Blocks
+
+Indent code by 4 spaces or 1 tab:
+
+```markdown
+This is a paragraph.
+
+    def hello
+      puts "world"
+    end
+
+This is another paragraph.
+```
+
+#### Fenced Code Blocks
+
+Use triple backticks with an optional language identifier:
+
+    ```ruby
+    def hello
+      puts "world"
+    end
+    ```
+
+Supported language for syntax highlighting: `ruby`, `rb` (alias to `ruby`), and `c`.
+
+### Blockquotes
+
+Prefix lines with `>`:
+
+```markdown
+> This is a blockquote.
+> It can span multiple lines.
+>
+> Multiple paragraphs are supported.
+```
+
+Blockquotes can contain other elements:
+
+```markdown
+> ## Heading inside blockquote
+>
+> - List item 1
+> - List item 2
+>
+> Code inside blockquote:
+>
+>     def example
+>       :ok
+>     end
+```
+
+Nested blockquotes:
+
+```markdown
+> Outer quote
+>
+> > Nested quote
+```
+
+### Lists
+
+#### Bullet Lists
+
+Use `*`, `+`, or `-` followed by a space:
+
+```markdown
+* Item 1
+* Item 2
+* Item 3
+```
+
+Or:
+
+```markdown
+- Item 1
+- Item 2
+- Item 3
+```
+
+#### Numbered Lists
+
+Use digits followed by `.` and a space:
+
+```markdown
+1. First item
+2. Second item
+3. Third item
+```
+
+The actual numbers don't matter; they're renumbered in output:
+
+```markdown
+1. First
+1. Second
+1. Third
+```
+
+#### Nested Lists
+
+Indent with 4 spaces to nest:
+
+```markdown
+* Item 1
+    * Nested item A
+    * Nested item B
+* Item 2
+    1. Numbered nested
+    2. Also numbered
+```
+
+#### Definition Lists
+
+Use a term on one line, then `:` followed by the definition:
+
+```markdown
+term
+:   Definition of the term.
+
+cat
+:   A small furry mammal.
+
+ant
+:   A little insect.
+```
+
+Multiple definitions for one term:
+
+```markdown
+apple
+:   A fruit
+:   A technology company
+```
+
+### Tables
+
+Create tables with pipes and dashes:
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+```
+
+#### Column Alignment
+
+Use colons to specify alignment:
+
+```markdown
+| Left     | Center   | Right    |
+|:---------|:--------:|---------:|
+| Left     | Center   | Right    |
+| aligned  | aligned  | aligned  |
+```
+
+- `:---` or `---` for left alignment (default)
+- `:---:` for center alignment
+- `---:` for right alignment
+
+Tables support inline formatting in cells:
+
+```markdown
+| Feature     | Syntax          |
+|-------------|-----------------|
+| **Bold**    | `**text**`      |
+| *Italic*    | `*text*`        |
+| `Code`      | `` `text` ``    |
+```
+
+### Horizontal Rules
+
+Use three or more `-`, `*`, or `_` on a line by themselves:
+
+```markdown
+---
+
+* * *
+
+___
+```
+
+## Text Markup
+
+Inline text can be formatted with various markup:
+
+- [Italic](#italic): emphasized text.
+- [Bold](#bold): strong emphasis.
+- [Bold and Italic](#bold-and-italic): combined emphasis.
+- [Strikethrough](#strikethrough): deleted text.
+- [Inline Code](#inline-code): monospace text.
+
+### Italic
+
+Use single asterisks or underscores:
+
+```markdown
+This is *italic* text.
+This is _also italic_ text.
+```
+
+> This is *italic* text.
+> This is _also italic_ text.
+
+**Note:** Underscores within words are not interpreted as emphasis:
+
+```markdown
+foo_bar_baz remains plain text
+```
+
+### Bold
+
+Use double asterisks or underscores:
+
+```markdown
+This is **bold** text.
+This is __also bold__ text.
+```
+
+> This is **bold** text.
+> This is __also bold__ text.
+
+### Bold and Italic
+
+Use triple asterisks or underscores:
+
+```markdown
+This is ***bold and italic*** text.
+This is ___also bold and italic___ text.
+```
+
+> This is ***bold and italic*** text.
+> This is ___also bold and italic___ text.
+
+### Strikethrough
+
+Use double tildes:
+
+```markdown
+This is ~~strikethrough~~ text.
+```
+
+> This is ~~strikethrough~~ text.
+
+### Inline Code
+
+Use backticks:
+
+```markdown
+Use the `puts` method.
+```
+
+> Use the `puts` method.
+
+For code containing backticks, use multiple backticks:
+
+```markdown
+Use `` `backticks` `` in code.
+```
+
+> Use `` `backticks` `` in code.
+
+## Links
+
+### Inline Links
+
+```markdown
+[Link text](https://example.com)
+```
+
+> [Link text](https://example.com)
+
+With optional title (title is parsed but not used in RDoc output):
+
+```markdown
+[Link text](https://example.com "Title")
+```
+
+### Reference Links
+
+Define a reference, then use it:
+
+```markdown
+[Link text][ref]
+
+[ref]: https://example.com
+```
+
+Implicit reference (link text matches reference):
+
+```markdown
+[Example][]
+
+[Example]: https://example.com
+```
+
+### Autolinks
+
+URLs and emails in angle brackets become links:
+
+```markdown
+<https://example.com>
+<user@example.com>
+```
+
+> <https://example.com>
+> <user@example.com>
+
+### Cross-References
+
+Link to RDoc-documented classes, modules, and methods:
+
+```markdown
+[RDoc module](rdoc-ref:RDoc)
+[Options class](rdoc-ref:RDoc::Options)
+[document method](rdoc-ref:RDoc::RDoc#document)
+```
+
+See [rdoc.rdoc](rdoc.rdoc) for complete cross-reference documentation.
+
+## Images
+
+Basic image syntax:
+
+```markdown
+![Alt text](path/to/image.png)
+```
+
+Image as a link:
+
+```markdown
+[![Alt text](image.png)](https://example.com)
+```
+
+## Anchor Links
+
+RDoc supports GitHub-style anchor links. You can link to any heading using its
+anchor, which is the heading text converted to lowercase with spaces replaced
+by hyphens and special characters removed.
+
+For example:
+
+* [Link to Footnotes](#footnotes)
+* [Link to Blockquotes](#blockquotes)
+* [Link to Anchor Links](#anchor-links)
+
+## Footnotes
+
+### Reference Footnotes
+
+Add a footnote reference in text, then define it:
+
+```markdown
+Here is some text[^1] with a footnote[^note].
+
+[^1]: This is the first footnote.
+[^note]: This is another footnote.
+```
+
+### Inline Footnotes
+
+Create footnotes inline:
+
+```markdown
+Here is text ^[with an inline footnote].
+```
+
+Footnotes are collected and rendered at the bottom of the section,
+separated by a horizontal rule.
+
+## HTML
+
+### Block HTML
+
+Raw HTML blocks are preserved:
+
+```markdown
+<div class="note">
+  <p>This is HTML content.</p>
+</div>
+```
+
+Supported block-level tags include: `<address>`, `<blockquote>`, `<div>`,
+`<fieldset>`, `<form>`, `<h1>`-`<h6>`, `<ol>`, `<p>`, `<pre>`, `<table>`, `<ul>`.
+
+### Inline HTML
+
+Inline HTML is also preserved:
+
+```markdown
+This has <b>bold</b> and <em>emphasized</em> HTML.
+```
+
+## Special Characters
+
+### Escaping
+
+Use backslash to escape special characters:
+
+```markdown
+\*not italic\*
+\`not code\`
+\[not a link\]
+\# not a heading
+```
+
+Escapable characters: `` ` \ : | * _ { } [ ] ( ) # + . ! > < - ``
+
+### HTML Entities
+
+Named, decimal, and hexadecimal entities are supported:
+
+```markdown
+&copy; &mdash; &pi;
+&#65; &#x41;
+```
+
+## Line Breaks
+
+End a line with two or more spaces for a hard line break:
+
+```markdown
+Line one
+Line two
+```
+
+## Directives
+
+RDoc directives work in Markdown files within Ruby comments.
+Use the `:markup: markdown` directive to specify Markdown format.
+
+```ruby
+# :markup: markdown
+
+# This class uses **Markdown** for documentation.
+#
+# ## Features
+#
+# - Bold with `**text**`
+# - Italic with `*text*`
+class MyClass
+end
+```
+
+Common directives (same as RDoc markup):
+
+- `:nodoc:` - Suppress documentation
+- `:doc:` - Force documentation
+- `:stopdoc:` / `:startdoc:` - Start/stop documentation parsing
+- `:call-seq:` - Custom calling sequence
+- `:section:` - Create documentation sections
+
+See [rdoc.rdoc](rdoc.rdoc) for complete directive documentation.
+
+## Comparison with RDoc Markup
+
+| Feature | RDoc Markup | Markdown |
+|---------|-------------|----------|
+| Headings | `= Heading` | `# Heading` |
+| Bold | `*word*` | `**word**` |
+| Italic | `_word_` | `*word*` |
+| Monospace | `+word+` | `` `word` `` |
+| Links | `{text}[url]` | `[text](url)` |
+| Code blocks | Indent beyond margin | Indent 4 spaces or fence |
+| Block quotes | `>>>` | `>` |
+| Tables | Not supported | Supported |
+| Strikethrough | `<del>text</del>` | `~~text~~` |
+| Footnotes | Not supported | `[^1]` |
+
+## Notes and Limitations
+
+1. **Link titles are parsed but not used** - The title in `[text](url "title")` is ignored.
+
+2. **Underscores in words** - `foo_bar` is never italicized; emphasis requires whitespace boundaries.
+
+3. **Footnotes are collapsed** - Multiple paragraphs in a footnote become a single paragraph.
+
+4. **Syntax highlighting** - Only `ruby` and `c` are supported for fenced code blocks.
+
+5. **Fenced code blocks** - Only triple backticks are supported. Tilde fences (`~~~`) are not supported as they conflict with strikethrough syntax. Four or more backticks for nesting are also not supported.
+
+6. **Auto-linking** - RDoc automatically links class and method names in output, even without explicit link syntax.