Self Documentation

Flex is aware of your templates, partials, the tags they use, whether they are required or have defaults, and can suggest you the usage of the methods it creates for you.

You can get the complete info, with the (erb expanded) templates and partials used by each generated method, plus a commented example of its usage, by just calling doc on the flex proxy object of your class. For example:

>> MyClass.flex.doc :facet_search

#  ########## MyClass.facet_search ##########
#
#  ----------------------
#  Flex::Template::Search
#  ---
#  facet_search:
#    - query:
#        bool:
#          must:
#            - query_string:
#                query: <<q= '*' >>
#            - << _facet_terms= ~ >>
#      facets:
#        keywords:
#          terms:
#            field: keywords
#        foo:
#          terms:
#            field: foo
#        bar:
#          terms:
#            field: bar
#
#  -----------------------
#  Flex::Template::Partial
#  ---
#  _facet_terms:
#    term: <<facet_hash>>
#
#
#  Usage:
#  MyClass.facet_search :_facet_terms => nil,         # partial
#                       :type         => type,        # required
#                       :index        => "test",
#                       :q            => "*"
#
def MyClass.facet_search(*vars)
  # this is a stub, used for reference
end

The info for a method contains the template and partial(s) eventually used, plus an usage example.

IMPORTANT: the usage example is not generic. It actually shows you a working sample of code, with the variables set with their evaluated default coming from your code or with a stub variable name. Keep an eye on the values of the variables in order to know more about them.

• If it is an explicit value, that is the default that will be used if you don’t pass any other value. Remember that a nil default would prune that tag if you don’t pass any other value.
• If it is a stub variable name, that means that it is a required tag (with no default), so you must pass the variable or it will raise an error.
• The explicit comments are shown in order to make partials and required variables stand out.

That output is suitable for being copied and pasted right in your class, just before the flex.load_* call that will overrides the stubs. Notice that stubs are very useful in order to make some IDE work properly with autogenerated methods (e.g. RubyMine).

You can get the self documetation of all the methods your class defines, by just not passing any template name to the doc method.

Notice: you can get the self documentation also for the Flex API Pethods by doing the same with Flex (see API Methods):

>> Flex.doc