module Brainstem

The Brainstem module itself contains a default_namespace class attribute and a few helpers that make managing PresenterCollections and their corresponding namespaces easier.

The Atlas is an object that makes the information from an introspector available in formatted and raw format.

This class describes the main API surface for generating API documentation. The command-line utility provided with Brainstem is basically just a thin veneer over top of this class.

You can use this to programmatically generate the API docs, or to browse them while inside a REPL.

Per-endpoint holder for presenter and controller information.

A formatter is fundamentally just a function that, when +#call+ed, accepts an atlas and returns the whole or portion of its data in a readable format.

There are (informally) several types of formatters, and you should select among them appropriately when developing your own:

1. Entity

   Turns a single data entity into its formatted version. For example, if
   formatting a Post object, call this formatter a
   +<Format>PostFormatter+.

2. Collection

   Turns a collection of formatted data entities into a single unit.
   Usually this will involve concatenating and/or rejecting inappropriate
   output. For example, if you have a collection of Markdown strings from
   the MarkdownPostFormatter, you might want to generate the whole section
   of documentation by using a +MarkdownPostCollectionFormatter+.

3. Aggregate

   A combination of entity and collection formatters. Knows how to turn a
   collection of unformatted entities into a single formatted document.
   Not as composable as the two used seperately, but far simpler. This
   should be named +MarkdownAggregatePostFormatter+.

At the time of writing, there is no actual requirement to use these naming conventions, but it is highly recommended for clarity of purpose.

Responsible for formatting each endpoint.

Responsible for formatting each endpoint.

This is a very simple DSL that makes generating a markdown document a bit easier.

Responsible for formatting each endpoint.

Responsible for formatting a response for an endpoint.

Responsible for formatting each endpoint.

Responsible for formatting each endpoint.

Wrapper for common presenter information lookups.

The Resolver is responsible for taking a non-ApiDocs class and turning it into an ApiDocs wrapper class (such as a Presenter, Controller, or Endpoint).

It's useful for doing object lookups for associated objects where we only have the original class or constant to look up the relationship.

General manager for CLI requests. Takes incoming user input and routes to a subcommand.

A Command is a callable object that acts as an entrypoint into the application logic. It is responsible for translating given options into specific enquiries.

Internally, it wraps an OptionParser instance returned through its +option_parser` method. The evaluation of this parser mutates the options hash. This is available to the call method on the instance, which is the primary point of application logic execution.

The GenerateApiDocsCommand is responsible for the construction and intermediation of the two primary components of automatic API doc generation.

It instantiates both a Builder, which is responsible for introspecting and validation of the host application, and also passes the Builder-generated data structure to the Sink, which is responsible for serializing the data structure to some store (likely transforming the data along the way).

Provide `brainstem_model_name` and `brainstem_plural_model_name` in controllers for use when accessing the `params` hash.

This module is used in lieu of an dependency on optional kwargs. Any symbol included in the array of #valid_options will be whitelisted from passed options and sent to the instance on initialization.

In this simple way, we can make classes accept options, whitelist which are acceptable, and set them without having to manually extend our initializer.

In order to use this, your constructor must have an argument named options that defaults to an empty hash. Additionally, for each option you define, you should define an accessor or at least a writer.

You may also implement a #valid_options method. It is recommended that you make this the union of the superclass's valid_options method and this class's options so that inherited options are preserved:

@example

def valid_options
  super | [ :your_options_here ]
end

A hash-like object that accepts a parent configuration object that defers to the parent in the absence of one of its own keys (thus simulating inheritance).

Brainstem::PresenterValidator is a helper class that performs validity checks on a given presenter class.