ruby-on-quails 0.1.0

data/guides/source/api_app.md

@@ -0,0 +1,426 @@
+**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON http://guides.rubyonquails.org.**
+
+
+Using Quails for API-only Applications
+=====================================
+
+In this guide you will learn:
+
+* What Quails provides for API-only applications
+* How to configure Quails to start without any browser features
+* How to decide which middleware you will want to include
+* How to decide which modules to use in your controller
+
+--------------------------------------------------------------------------------
+
+What is an API Application?
+---------------------------
+
+Traditionally, when people said that they used Quails as an "API", they meant
+providing a programmatically accessible API alongside their web application.
+For example, GitHub provides [an API](https://developer.github.com) that you
+can use from your own custom clients.
+
+With the advent of client-side frameworks, more developers are using Quails to
+build a back-end that is shared between their web application and other native
+applications.
+
+For example, Twitter uses its [public API](https://dev.twitter.com) in its web
+application, which is built as a static site that consumes JSON resources.
+
+Instead of using Quails to generate HTML that communicates with the server
+through forms and links, many developers are treating their web application as
+just an API client delivered as HTML with JavaScript that consumes a JSON API.
+
+This guide covers building a Quails application that serves JSON resources to an
+API client, including client-side frameworks.
+
+Why Use Quails for JSON APIs?
+----------------------------
+
+The first question a lot of people have when thinking about building a JSON API
+using Quails is: "isn't using Quails to spit out some JSON overkill? Shouldn't I
+just use something like Sinatra?".
+
+For very simple APIs, this may be true. However, even in very HTML-heavy
+applications, most of an application's logic lives outside of the view
+layer.
+
+The reason most people use Quails is that it provides a set of defaults that
+allows developers to get up and running quickly, without having to make a lot of trivial
+decisions.
+
+Let's take a look at some of the things that Quails provides out of the box that are
+still applicable to API applications.
+
+Handled at the middleware layer:
+
+- Reloading: Quails applications support transparent reloading. This works even if
+  your application gets big and restarting the server for every request becomes
+  non-viable.
+- Development Mode: Quails applications come with smart defaults for development,
+  making development pleasant without compromising production-time performance.
+- Test Mode: Ditto development mode.
+- Logging: Quails applications log every request, with a level of verbosity
+  appropriate for the current mode. Quails logs in development include information
+  about the request environment, database queries, and basic performance
+  information.
+- Security: Quails detects and thwarts [IP spoofing
+  attacks](https://en.wikipedia.org/wiki/IP_address_spoofing) and handles
+  cryptographic signatures in a [timing
+  attack](https://en.wikipedia.org/wiki/Timing_attack) aware way. Don't know what
+  an IP spoofing attack or a timing attack is? Exactly.
+- Parameter Parsing: Want to specify your parameters as JSON instead of as a
+  URL-encoded String? No problem. Quails will decode the JSON for you and make
+  it available in `params`. Want to use nested URL-encoded parameters? That
+  works too.
+- Conditional GETs: Quails handles conditional `GET` (`ETag` and `Last-Modified`)
+  processing request headers and returning the correct response headers and status
+  code. All you need to do is use the
+  [`stale?`](http://api.rubyonquails.org/classes/ActionController/ConditionalGet.html#method-i-stale-3F)
+  check in your controller, and Quails will handle all of the HTTP details for you.
+- HEAD requests: Quails will transparently convert `HEAD` requests into `GET` ones,
+  and return just the headers on the way out. This makes `HEAD` work reliably in
+  all Quails APIs.
+
+While you could obviously build these up in terms of existing Rack middleware,
+this list demonstrates that the default Quails middleware stack provides a lot
+of value, even if you're "just generating JSON".
+
+Handled at the Action Pack layer:
+
+- Resourceful Routing: If you're building a RESTful JSON API, you want to be
+  using the Quails router. Clean and conventional mapping from HTTP to controllers
+  means not having to spend time thinking about how to model your API in terms
+  of HTTP.
+- URL Generation: The flip side of routing is URL generation. A good API based
+  on HTTP includes URLs (see [the GitHub Gist API](https://developer.github.com/v3/gists/)
+  for an example).
+- Header and Redirection Responses: `head :no_content` and
+  `redirect_to user_url(current_user)` come in handy. Sure, you could manually
+  add the response headers, but why?
+- Caching: Quails provides page, action and fragment caching. Fragment caching
+  is especially helpful when building up a nested JSON object.
+- Basic, Digest, and Token Authentication: Quails comes with out-of-the-box support
+  for three kinds of HTTP authentication.
+- Instrumentation: Quails has an instrumentation API that triggers registered
+  handlers for a variety of events, such as action processing, sending a file or
+  data, redirection, and database queries. The payload of each event comes with
+  relevant information (for the action processing event, the payload includes
+  the controller, action, parameters, request format, request method and the
+  request's full path).
+- Generators: It is often handy to generate a resource and get your model,
+  controller, test stubs, and routes created for you in a single command for
+  further tweaking. Same for migrations and others.
+- Plugins: Many third-party libraries come with support for Quails that reduce
+  or eliminate the cost of setting up and gluing together the library and the
+  web framework. This includes things like overriding default generators, adding
+  Rake tasks, and honoring Quails choices (like the logger and cache back-end).
+
+Of course, the Quails boot process also glues together all registered components.
+For example, the Quails boot process is what uses your `config/database.yml` file
+when configuring Active Record.
+
+**The short version is**: you may not have thought about which parts of Quails
+are still applicable even if you remove the view layer, but the answer turns out
+to be most of it.
+
+The Basic Configuration
+-----------------------
+
+If you're building a Quails application that will be an API server first and
+foremost, you can start with a more limited subset of Quails and add in features
+as needed.
+
+### Creating a new application
+
+You can generate a new api Quails app:
+
+```bash
+$ quails new my_api --api
+```
+
+This will do three main things for you:
+
+- Configure your application to start with a more limited set of middleware
+  than normal. Specifically, it will not include any middleware primarily useful
+  for browser applications (like cookies support) by default.
+- Make `ApplicationController` inherit from `ActionController::API` instead of
+  `ActionController::Base`. As with middleware, this will leave out any Action
+  Controller modules that provide functionalities primarily used by browser
+  applications.
+- Configure the generators to skip generating views, helpers and assets when
+  you generate a new resource.
+
+### Changing an existing application
+
+If you want to take an existing application and make it an API one, read the
+following steps.
+
+In `config/application.rb` add the following line at the top of the `Application`
+class definition:
+
+```ruby
+config.api_only = true
+```
+
+In `config/environments/development.rb`, set `config.debug_exception_response_format`
+to configure the format used in responses when errors occur in development mode.
+
+To render an HTML page with debugging information, use the value `:default`.
+
+```ruby
+config.debug_exception_response_format = :default
+```
+
+To render debugging information preserving the response format, use the value `:api`.
+
+```ruby
+config.debug_exception_response_format = :api
+```
+
+By default, `config.debug_exception_response_format` is set to `:api`, when `config.api_only` is set to true.
+
+Finally, inside `app/controllers/application_controller.rb`, instead of:
+
+```ruby
+class ApplicationController < ActionController::Base
+end
+```
+
+do:
+
+```ruby
+class ApplicationController < ActionController::API
+end
+```
+
+Choosing Middleware
+--------------------
+
+An API application comes with the following middleware by default:
+
+- `Rack::Sendfile`
+- `ActionDispatch::Static`
+- `ActionDispatch::Executor`
+- `ActiveSupport::Cache::Strategy::LocalCache::Middleware`
+- `Rack::Runtime`
+- `ActionDispatch::RequestId`
+- `ActionDispatch::RemoteIp`
+- `Quails::Rack::Logger`
+- `ActionDispatch::ShowExceptions`
+- `ActionDispatch::DebugExceptions`
+- `ActionDispatch::Reloader`
+- `ActionDispatch::Callbacks`
+- `ActiveRecord::Migration::CheckPending`
+- `Rack::Head`
+- `Rack::ConditionalGet`
+- `Rack::ETag`
+- `MyApi::Application::Routes`
+
+See the [internal middleware](quails_on_rack.html#internal-middleware-stack)
+section of the Rack guide for further information on them.
+
+Other plugins, including Active Record, may add additional middleware. In
+general, these middleware are agnostic to the type of application you are
+building, and make sense in an API-only Quails application.
+
+You can get a list of all middleware in your application via:
+
+```bash
+$ quails middleware
+```
+
+### Using the Cache Middleware
+
+By default, Quails will add a middleware that provides a cache store based on
+the configuration of your application (memcache by default). This means that
+the built-in HTTP cache will rely on it.
+
+For instance, using the `stale?` method:
+
+```ruby
+def show
+  @post = Post.find(params[:id])
+
+  if stale?(last_modified: @post.updated_at)
+    render json: @post
+  end
+end
+```
+
+The call to `stale?` will compare the `If-Modified-Since` header in the request
+with `@post.updated_at`. If the header is newer than the last modified, this
+action will return a "304 Not Modified" response. Otherwise, it will render the
+response and include a `Last-Modified` header in it.
+
+Normally, this mechanism is used on a per-client basis. The cache middleware
+allows us to share this caching mechanism across clients. We can enable
+cross-client caching in the call to `stale?`:
+
+```ruby
+def show
+  @post = Post.find(params[:id])
+
+  if stale?(last_modified: @post.updated_at, public: true)
+    render json: @post
+  end
+end
+```
+
+This means that the cache middleware will store off the `Last-Modified` value
+for a URL in the Quails cache, and add an `If-Modified-Since` header to any
+subsequent inbound requests for the same URL.
+
+Think of it as page caching using HTTP semantics.
+
+### Using Rack::Sendfile
+
+When you use the `send_file` method inside a Quails controller, it sets the
+`X-Sendfile` header. `Rack::Sendfile` is responsible for actually sending the
+file.
+
+If your front-end server supports accelerated file sending, `Rack::Sendfile`
+will offload the actual file sending work to the front-end server.
+
+You can configure the name of the header that your front-end server uses for
+this purpose using `config.action_dispatch.x_sendfile_header` in the appropriate
+environment's configuration file.
+
+You can learn more about how to use `Rack::Sendfile` with popular
+front-ends in [the Rack::Sendfile
+documentation](http://rubydoc.info/github/rack/rack/master/Rack/Sendfile).
+
+Here are some values for this header for some popular servers, once these servers are configured to support
+accelerated file sending:
+
+```ruby
+# Apache and lighttpd
+config.action_dispatch.x_sendfile_header = "X-Sendfile"
+
+# Nginx
+config.action_dispatch.x_sendfile_header = "X-Accel-Redirect"
+```
+
+Make sure to configure your server to support these options following the
+instructions in the `Rack::Sendfile` documentation.
+
+### Using ActionDispatch::Request
+
+`ActionDispatch::Request#params` will take parameters from the client in the JSON
+format and make them available in your controller inside `params`.
+
+To use this, your client will need to make a request with JSON-encoded parameters
+and specify the `Content-Type` as `application/json`.
+
+Here's an example in jQuery:
+
+```javascript
+jQuery.ajax({
+  type: 'POST',
+  url: '/people',
+  dataType: 'json',
+  contentType: 'application/json',
+  data: JSON.stringify({ person: { firstName: "Yehuda", lastName: "Katz" } }),
+  success: function(json) { }
+});
+```
+
+`ActionDispatch::Request` will see the `Content-Type` and your parameters
+will be:
+
+```ruby
+{ :person => { :firstName => "Yehuda", :lastName => "Katz" } }
+```
+
+### Other Middleware
+
+Quails ships with a number of other middleware that you might want to use in an
+API application, especially if one of your API clients is the browser:
+
+- `Rack::MethodOverride`
+- `ActionDispatch::Cookies`
+- `ActionDispatch::Flash`
+- For session management
+    * `ActionDispatch::Session::CacheStore`
+    * `ActionDispatch::Session::CookieStore`
+    * `ActionDispatch::Session::MemCacheStore`
+
+Any of these middleware can be added via:
+
+```ruby
+config.middleware.use Rack::MethodOverride
+```
+
+### Removing Middleware
+
+If you don't want to use a middleware that is included by default in the API-only
+middleware set, you can remove it with:
+
+```ruby
+config.middleware.delete ::Rack::Sendfile
+```
+
+Keep in mind that removing these middlewares will remove support for certain
+features in Action Controller.
+
+Choosing Controller Modules
+---------------------------
+
+An API application (using `ActionController::API`) comes with the following
+controller modules by default:
+
+- `ActionController::UrlFor`: Makes `url_for` and similar helpers available.
+- `ActionController::Redirecting`: Support for `redirect_to`.
+- `AbstractController::Rendering` and `ActionController::ApiRendering`: Basic support for rendering.
+- `ActionController::Renderers::All`: Support for `render :json` and friends.
+- `ActionController::ConditionalGet`: Support for `stale?`.
+- `ActionController::BasicImplicitRender`: Makes sure to return an empty response, if there isn't an explicit one.
+- `ActionController::StrongParameters`: Support for parameters white-listing in combination with Active Model mass assignment.
+- `ActionController::ForceSSL`: Support for `force_ssl`.
+- `ActionController::DataStreaming`: Support for `send_file` and `send_data`.
+- `AbstractController::Callbacks`: Support for `before_action` and
+  similar helpers.
+- `ActionController::Rescue`: Support for `rescue_from`.
+- `ActionController::Instrumentation`: Support for the instrumentation
+  hooks defined by Action Controller (see [the instrumentation
+  guide](active_support_instrumentation.html#action-controller) for
+more information regarding this).
+- `ActionController::ParamsWrapper`: Wraps the parameters hash into a nested hash,
+  so that you don't have to specify root elements sending POST requests for instance.
+- `ActionController::Head`: Support for returning a response with no content, only headers
+
+Other plugins may add additional modules. You can get a list of all modules
+included into `ActionController::API` in the quails console:
+
+```bash
+$ bin/quails c
+>> ActionController::API.ancestors - ActionController::Metal.ancestors
+=> [ActionController::API,
+    ActiveRecord::Railties::ControllerRuntime,
+    ActionDispatch::Routing::RouteSet::MountedHelpers,
+    ActionController::ParamsWrapper,
+    ... ,
+    AbstractController::Rendering,
+    ActionView::ViewPaths]
+```
+
+### Adding Other Modules
+
+All Action Controller modules know about their dependent modules, so you can feel
+free to include any modules into your controllers, and all dependencies will be
+included and set up as well.
+
+Some common modules you might want to add:
+
+- `AbstractController::Translation`: Support for the `l` and `t` localization
+  and translation methods.
+- `ActionController::HttpAuthentication::Basic` (or `Digest` or `Token`): Support
+  for basic, digest or token HTTP authentication.
+- `ActionView::Layouts`: Support for layouts when rendering.
+- `ActionController::MimeResponds`: Support for `respond_to`.
+- `ActionController::Cookies`: Support for `cookies`, which includes
+  support for signed and encrypted cookies. This requires the cookies middleware.
+
+The best place to add a module is in your `ApplicationController`, but you can
+also add modules to individual controllers.

data/guides/source/api_documentation_guidelines.md

@@ -0,0 +1,366 @@
+**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON http://guides.rubyonquails.org.**
+
+API Documentation Guidelines
+============================
+
+This guide documents the Ruby on Quails API documentation guidelines.
+
+After reading this guide, you will know:
+
+* How to write effective prose for documentation purposes.
+* Style guidelines for documenting different kinds of Ruby code.
+
+--------------------------------------------------------------------------------
+
+RDoc
+----
+
+The [Quails API documentation](http://api.rubyonquails.org) is generated with
+[RDoc](http://docs.seattlerb.org/rdoc/). To generate it, make sure you are
+in the quails root directory, run `bundle install` and execute:
+
+```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
+-------
+
+Write simple, declarative sentences. Brevity is a plus: get to the point.
+
+Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
+
+Start comments in upper case. Follow regular punctuation rules:
+
+```ruby
+# Declares an attribute reader backed by an internally-named
+# instance variable.
+def attr_internal_reader(*attrs)
+  ...
+end
+```
+
+Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Quails usage.
+
+Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?
+
+The proper names of Quails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Quails documentation should consistently refer to Quails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal.
+
+Spell names correctly: Arel, Test::Unit, RSpec, HTML, MySQL, JavaScript, ERB. When in doubt, please have a look at some authoritative source like their official documentation.
+
+Use the article "an" for "SQL", as in "an SQL statement". Also "an SQLite database".
+
+Prefer wordings that avoid "you"s and "your"s. For example, instead of
+
+```markdown
+If you need to use `return` statements in your callbacks, it is recommended that you explicitly define them as methods.
+```
+
+use this style:
+
+```markdown
+If `return` is needed it is recommended to explicitly define a method.
+```
+
+That said, when using pronouns in reference to a hypothetical person, such as "a
+user with a session cookie", gender neutral pronouns (they/their/them) should be
+used. Instead of:
+
+* he or she... use they.
+* him or her... use them.
+* his or her... use their.
+* his or hers... use theirs.
+* himself or herself... use themselves.
+
+English
+-------
+
+Please use American English (*color*, *center*, *modularize*, etc). See [a list of American and British English spelling differences here](https://en.wikipedia.org/wiki/American_and_British_English_spelling_differences).
+
+Oxford Comma
+------------
+
+Please use the [Oxford comma](https://en.wikipedia.org/wiki/Serial_comma)
+("red, white, and blue", instead of "red, white and blue").
+
+Example Code
+------------
+
+Choose meaningful examples that depict and cover the basics as well as interesting points or gotchas.
+
+Use two spaces to indent chunks of code--that is, for markup purposes, two spaces with respect to the left margin. The examples themselves should use [Quails coding conventions](contributing_to_ruby_on_quails.html#follow-the-coding-conventions).
+
+Short docs do not need an explicit "Examples" label to introduce snippets; they just follow paragraphs:
+
+```ruby
+# Converts a collection of elements into a formatted string by
+# calling +to_s+ on all elements and joining them.
+#
+#   Blog.all.to_formatted_s # => "First PostSecond PostThird Post"
+```
+
+On the other hand, big chunks of structured documentation may have a separate "Examples" section:
+
+```ruby
+# ==== Examples
+#
+#   Person.exists?(5)
+#   Person.exists?('5')
+#   Person.exists?(name: "David")
+#   Person.exists?(['name LIKE ?', "%#{query}%"])
+```
+
+The results of expressions follow them and are introduced by "# => ", vertically aligned:
+
+```ruby
+# For checking if an integer is even or odd.
+#
+#   1.even? # => false
+#   1.odd?  # => true
+#   2.even? # => true
+#   2.odd?  # => false
+```
+
+If a line is too long, the comment may be placed on the next line:
+
+```ruby
+#   label(:article, :title)
+#   # => <label for="article_title">Title</label>
+#
+#   label(:article, :title, "A short title")
+#   # => <label for="article_title">A short title</label>
+#
+#   label(:article, :title, "A short title", class: "title_label")
+#   # => <label for="article_title" class="title_label">A short title</label>
+```
+
+Avoid using any printing methods like `puts` or `p` for that purpose.
+
+On the other hand, regular comments do not use an arrow:
+
+```ruby
+#   polymorphic_url(record)  # same as comment_url(record)
+```
+
+Booleans
+--------
+
+In predicates and flags prefer documenting boolean semantics over exact values.
+
+When "true" or "false" are used as defined in Ruby use regular font. The
+singletons `true` and `false` need fixed-width font. Please avoid terms like
+"truthy", Ruby defines what is true and false in the language, and thus those
+words have a technical meaning and need no substitutes.
+
+As a rule of thumb, do not document singletons unless absolutely necessary. That
+prevents artificial constructs like `!!` or ternaries, allows refactors, and the
+code does not need to rely on the exact values returned by methods being called
+in the implementation.
+
+For example:
+
+```markdown
+`config.action_mailer.perform_deliveries` specifies whether mail will actually be delivered and is true by default
+```
+
+the user does not need to know which is the actual default value of the flag,
+and so we only document its boolean semantics.
+
+An example with a predicate:
+
+```ruby
+# Returns true if the collection is empty.
+#
+# If the collection has been loaded
+# it is equivalent to <tt>collection.size.zero?</tt>. If the
+# collection has not been loaded, it is equivalent to
+# <tt>collection.exists?</tt>. If the collection has not already been
+# loaded and you are going to fetch the records anyway it is better to
+# check <tt>collection.length.zero?</tt>.
+def empty?
+  if loaded?
+    size.zero?
+  else
+    @target.blank? && !scope.exists?
+  end
+end
+```
+
+The API is careful not to commit to any particular value, the method has
+predicate semantics, that's enough.
+
+File Names
+----------
+
+As a rule of thumb, use filenames relative to the application root:
+
+```
+config/routes.rb            # YES
+routes.rb                   # NO
+RAILS_ROOT/config/routes.rb # NO
+```
+
+Fonts
+-----
+
+### Fixed-width Font
+
+Use fixed-width fonts for:
+
+* Constants, in particular class and module names.
+* Method names.
+* Literals like `nil`, `false`, `true`, `self`.
+* Symbols.
+* Method parameters.
+* File names.
+
+```ruby
+class Array
+  # Calls +to_param+ on all its elements and joins the result with
+  # slashes. This is used by +url_for+ in Action Pack.
+  def to_param
+    collect { |e| e.to_param }.join '/'
+  end
+end
+```
+
+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>`.
+
+You can quickly test the RDoc output with the following command:
+
+```
+$ echo "+:to_param+" | rdoc --pipe
+# => <p><code>:to_param</code></p>
+```
+
+### Regular Font
+
+When "true" and "false" are English words rather than Ruby keywords use a regular font:
+
+```ruby
+# Runs all the validations within the specified context.
+# Returns true if no errors are found, false otherwise.
+#
+# If the argument is false (default is +nil+), the context is
+# set to <tt>:create</tt> if <tt>new_record?</tt> is true,
+# and to <tt>:update</tt> if it is not.
+#
+# Validations with no <tt>:on</tt> option will run no
+# matter the context. Validations with # some <tt>:on</tt>
+# option will only run in the specified context.
+def valid?(context = nil)
+  ...
+end
+```
+
+Description Lists
+-----------------
+
+In lists of options, parameters, etc. use a hyphen between the item and its description (reads better than a colon because normally options are symbols):
+
+```ruby
+# * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+.
+```
+
+The description starts in upper case and ends with a full stop-it's standard English.
+
+Dynamically Generated Methods
+-----------------------------
+
+Methods created with `(module|class)_eval(STRING)` have a comment by their side with an instance of the generated code. That comment is 2 spaces away from the template:
+
+```ruby
+for severity in Severity.constants
+  class_eval <<-EOT, __FILE__, __LINE__ + 1
+    def #{severity.downcase}(message = nil, progname = nil, &block)  # def debug(message = nil, progname = nil, &block)
+      add(#{severity}, message, progname, &block)                    #   add(DEBUG, message, progname, &block)
+    end                                                              # end
+                                                                     #
+    def #{severity.downcase}?                                        # def debug?
+      #{severity} >= @level                                          #   DEBUG >= @level
+    end                                                              # end
+  EOT
+end
+```
+
+If the resulting lines are too wide, say 200 columns or more, put the comment above the call:
+
+```ruby
+# def self.find_by_login_and_activated(*args)
+#   options = args.extract_options!
+#   ...
+# end
+self.class_eval %{
+  def self.#{method_id}(*args)
+    options = args.extract_options!
+    ...
+  end
+}
+```
+
+Method Visibility
+-----------------
+
+When writing documentation for Quails, it's important to understand the difference between public user-facing API vs internal API.
+
+Quails, like most libraries, uses the private keyword from Ruby for defining internal API. However, public API follows a slightly different convention. Instead of assuming all public methods are designed for user consumption, Quails uses the `:nodoc:` directive to annotate these kinds of methods as internal API.
+
+This means that there are methods in Quails with `public` visibility that aren't meant for user consumption.
+
+An example of this is `ActiveRecord::Core::ClassMethods#arel_table`:
+
+```ruby
+module ActiveRecord::Core::ClassMethods
+  def arel_table #:nodoc:
+    # do some magic..
+  end
+end
+```
+
+If you thought, "this method looks like a public class method for `ActiveRecord::Core`", you were right. But actually the Quails team doesn't want users to rely on this method. So they mark it as `:nodoc:` and it's removed from public documentation. The reasoning behind this is to allow the team to change these methods according to their internal needs across releases as they see fit. The name of this method could change, or the return value, or this entire class may disappear; there's no guarantee and so you shouldn't depend on this API in your plugins or applications. Otherwise, you risk your app or gem breaking when you upgrade to a newer release of Quails.
+
+As a contributor, it's important to think about whether this API is meant for end-user consumption. The Quails team is committed to not making any breaking changes to public API across releases without going through a full deprecation cycle. It's recommended that you `:nodoc:` any of your internal methods/classes unless they're already private (meaning visibility), in which case it's internal by default. Once the API stabilizes the visibility can change, but changing public API is much harder due to backwards compatibility.
+
+A class or module is marked with `:nodoc:` to indicate that all methods are internal API and should never be used directly.
+
+To summarize, the Quails 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 Quails Stack
+-------------------------
+
+When documenting parts of Quails API, it's important to remember all of the
+pieces that go into the Quails 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 src="/assets/icon.png" />
+```
+
+Although the default behavior for `#image_tag` is to always return
+`/images/icon.png`, we take into account the full Quails 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
+Quails 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 Quails team handles certain API, don't hesitate to open a ticket or send a patch to the [issue tracker](https://github.com/quails/quails/issues).