Permalink
Browse files

API guidelines: revises warning about +...+ [ci skip]

Modern RDoc accepts a few more things in +...+. In particular symbols work now.

The current regexp in RDoc is https://github.com/rdoc/rdoc/blob/v4.1.1/lib/rdoc/markup/attribute_manager.rb#L133.
  • Loading branch information...
1 parent 0df1f91 commit 225bcadfed9f901d97867f9f9371c0e62379cb0f @fxn fxn committed Jan 26, 2014
Showing with 4 additions and 1 deletion.
  1. +4 −1 guides/source/api_documentation_guidelines.md
@@ -163,7 +163,10 @@ class Array
end
```
-WARNING: Using a pair of `+...+` for fixed-width font only works with **words**; that is: anything matching `\A\w+\z`. For anything else use `<tt>...</tt>`, notably symbols, setters, inline snippets, etc.
+WARNING: Using `+...+` for fixed-width font only works with simple content like
+ordinary method names, symbols, paths (with forward slashes), etc. Please use
+`<tt>...</tt>` for everything else, notably class or module names with a
+namespace as in `<tt>ActiveRecord::Base</tt>`.
### Regular Font

6 comments on commit 225bcad

Member

zzak replied Feb 9, 2014

@fxn My general policy is use +...+ for single-word and (some) literals. And use <tt>...</tt> for multi-word and anything RDoc can't parse with +...+.

Member

zzak replied Feb 9, 2014

Also, $ echo "+foo+" | rdoc --pipe is a good method for testing what it can/can't parse.

Owner

fxn replied Feb 9, 2014

In the past RDoc was more strict, in particular symbols didn't work between +. That was the motivation for the remark this patch edits (I wrote that remark myself years ago).

The regepx accepts more stuff now, and in particular symbols are fine.

The tip about --pipe is good I believe we could add it.

Member

zzak replied Feb 9, 2014

@fxn I'll send a patch about --pipe, I don't think we should document the actual regex.

Owner

fxn replied Feb 11, 2014

👍

Please sign in to comment.