= Spec entity =

Spec entities correspond to ''-spec'' attributes in erlang sources. The specification for a given function is commonly present in the module where the function is defined, but it can also be placed in header files or other modules. A function might have more than one specification even if it consists of only one clause. Please note that in our representation, there is no "1:1" correlation between function clauses and ''-spec'' attributes, so any given function clause has all specs of the entire function.

== Initial selector ==
A ''-spec'' attribute can be indicated by a given position. In this case the {{{@spec}}} initial-selector returns the spec entity corresponding to the indicated attribute in the source.

== Selectors ==

''The type of the result elements are indicated in parenthesis.''

* {{{function}}} (''function''): The function that has this spec.
* {{{file}}} (''file''): The file in which the spec was defined.
* {{{refmod}}} (''file''): The file to which the spec pertains. (If a module identifier has been used in the spec, the result may differ from the defining file.)
* {{{returntype}}} (''type''): Possible return types of the spec.
* {{{guardtype}}} (''type''): Types of the spec-guards.
* {{{arguments}}} (''specparam''): Arguments of the spec.

== Properties ==

The following properties are defined for spec entities:

* {{{name}}} (''atom''): Name of the function spec.
* {{{arity}}} (''int''): Arity of the spec.
* {{{text}}} (''string''): String representation of the spec.
* {{{returntext}}} (''string''): String representation of the spec's return values.
* {{{guardtext}}} (''string''): String representation of the spec's guards.

== Textual output format ==

When using any of our interfaces, other than ris?, this entity will be represented in the output as a string with the same format as it was defined in the source file.

{{{
ri:q("mods.spec").
a.erl
    -spec io_lib:format(Format :: atom() | string() | binary(), D) -> [char] when D :: list(term()).
...
}}}

== Review of non-trivial selectors ==
For some of the selectors it may not be initially clear how and what would they return. A description of these can be found here: 

=== Spec.refmod: ===
Specs can have module-identifiers which determine the module whose function is being specified. This module is returned by the selector unless the module-identifier was omitted, in which case the defining module is returned.
{{{
ri:q("mods.spec.refmod").     
-spec io_lib:format(Format :: atom() | string() | binary(), D) -> [char] when D :: list(term()).
    io_lib
...
}}}

=== Spec.arguments: ===
Returns the type expression for the arguments of the specification. Argument-names are included.
{{{
ri:q("mods.spec.args").  
-spec io_lib:format(Format :: atom() | string() | binary(), D) -> [char] when D :: list(term()).
    Format :: atom() | string() | binary()
     D
...
}}}

=== Spec.guardtypes: ===
Returns the type expressions of spec-guards.
{{{
ri:q("mods.spec.guardtypes").
-spec io_lib:format(Format :: atom() | string() | binary(), D) -> [char] when D :: list(term()).
     D :: list(term())
...
}}}