diff options
Diffstat (limited to 'guides/source/api_documentation_guidelines.md')
| -rw-r--r-- | guides/source/api_documentation_guidelines.md | 46 |
1 files changed, 44 insertions, 2 deletions
diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index 2a3bb4e34d..d481700709 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -1,3 +1,5 @@ +**DO NOT READ THIS FILE IN GITHUB, GUIDES ARE PUBLISHED IN http://guides.rubyonrails.org.** + API Documentation Guidelines ============================ @@ -13,7 +15,19 @@ After reading this guide, you will know: RDoc ---- -The Rails API documentation is generated with RDoc. Please consult the documentation for help with the [markup](http://rdoc.rubyforge.org/RDoc/Markup.html), and also take into account these [additional directives](http://rdoc.rubyforge.org/RDoc/Parser/Ruby.html). +The [Rails API documentation](http://api.rubyonrails.org) is generated with +[RDoc](http://docs.seattlerb.org/rdoc/). + +```bash + bundle exec rake rdoc +``` + +Resulting HTML files can be found in the ./doc/rdoc directory. + +Please consult the RDoc documentation for help with the +[markup](http://docs.seattlerb.org/rdoc/RDoc/Markup.html), +and also take into account these [additional +directives](http://docs.seattlerb.org/rdoc/RDoc/Parser/Ruby.html). Wording ------- @@ -67,7 +81,7 @@ used. Instead of: English ------- -Please use American English (<em>color</em>, <em>center</em>, <em>modularize</em>, etc). See [a list of American and British English spelling differences here](http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences). +Please use American English (*color*, *center*, *modularize*, etc). See [a list of American and British English spelling differences here](http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences). Example Code ------------ @@ -318,4 +332,32 @@ A `:nodoc:` should never be added simply because a method or class is missing do To summarize, the Rails team uses `:nodoc:` to mark publicly visible methods and classes for internal use; changes to the visibility of API should be considered carefully and discussed over a pull request first. +Regarding the Rails Stack +------------------------- + +When documenting parts of Rails API, it's important to remember all of the +pieces that go into the Rails stack. + +This means that behavior may change depending on the scope or context of the +method or class you're trying to document. + +In various places there is different behavior when you take the entire stack +into account, one such example is +`ActionView::Helpers::AssetTagHelper#image_tag`: + +```ruby +# image_tag("icon.png") +# # => <img alt="Icon" src="/assets/icon.png" /> +``` + +Although the default behavior for `#image_tag` is to always return +`/images/icon.png`, we take into account the full Rails stack (including the +Asset Pipeline) we may see the result seen above. + +We're only concerned with the behavior experienced when using the full default +Rails stack. + +In this case, we want to document the behavior of the _framework_, and not just +this specific method. + If you have a question on how the Rails team handles certain API, don't hesitate to open a ticket or send a patch to the [issue tracker](https://github.com/rails/rails/issues). |