5 stars based on
Tags represent meta-data as well as behavioural data that can be added to documentation through the tag style syntax. As mentioned, there are two basic types of tags in YARD, "meta-data tags" and "behavioural tags", the latter is more often known as "directives". These two tag types can be visually identified by their prefix. Meta-data tags have a prefix, while directives have a prefix of!
The two tag types would be used in the yard hash options way, respectively:. This document describes how tags can be specified, how they affect your documentation, and how to use specific built-in tags in YARD, as well as how to define custom tags. Meta-data tags are useful to add arbitrary meta-data about a documented object.
These tags simply add data to objects that can be looked up later, either programmatically, or displayed in templates. The benefit to describing objects using meta-data tags is that your documentation can be organized semantically.
Rather than having a huge listing of text with no distinction of what each paragraph is discussing, tags allow you to focus in on specific elements of your documentation. For example, describing parameters of a method can often be important to your documentation, but should not yard hash options mixed up with the documentation that describes what the method itself does. In this case, separating the parameter documentation into param tags can yield much better organized documentation, both in source and in your output, without having to manually format the data yard hash options standard markup.
All of this meta-data can be easily parsed by tools and used both in your templates as well as in code checker tools. An example of how you can leverage tags programmatically is shown in the yard hash options tag, which lists a small snippet of Ruby code that can list all of your TODO items, if they are properly tagged.
Custom meta-data tags can be added either programmatically or via the YARD command-line. This is discussed in the " Adding Custom Tags yard hash options section. Directives are similar to meta-data tags in the way they are yard hash options, but they do not add meta-data to the object directly.
Instead, they affect the parsing context and objects themselves, allowing a developer to create objects like methods outright, rather than simply add text to an existing object.
A list of built-in directives are found below in the Directive List. Tags begin with the or! Unless otherwise specified by documentation for the tag, all "description" text is considered free-form data and can include any arbitrary textual data. Tags can span multiple lines if the subsequent lines are indented by more than one space. The typical convention is to indent subsequent lines by 2 spaces. In the following example, tagname will have the text "This is yard hash options tag data":.
Yard hash options most tags, newlines and indented data are not significant and do not impact the result of the tag. In other words, you can decide to yard hash options a tag onto multiple lines at any point by creating an indented block.
However, some tags like exampleoverload ,! For instance, the example tag uses the first line to indicate the example's title. Although custom tags can be parsed in any way, the built-in tags follow a few common syntax structures by convention in order to simplify the syntax. The following syntaxes are available:. In the tag list below, the term "description" implies freeform data, [Types] implies a types specifier list, "name" implies a name key, and "title" implies the first line is a newline significant field that cannot be split into multiple lines.
In some cases, a tag will allow for a "types specifier list"; this will be evident from the use of the [Types] syntax in the tag signature. A types specifier list is a comma separated yard hash options of types, most often classes or modules, but occasionally literals. For example, the following return tag lists a set of types returned by a method:. A list of conventions yard hash options type names is specified below. Duck-types method names prefixed with " " are also allowed.
Note that the type specifier list is always an optional field and can be omitted when present in a tag signature. This is the yard hash options why it is surrounded by brackets. It is also a freeform list, and can contain any list of values, though a set of conventions for how to list types is described below. A list of examples of common type listings and what they translate into is available at http: Typically, a type list contains a list of classes or modules that are associated with the tag.
In some cases, however, certain special values are allowed or required to be listed. This section discusses the syntax for specifying Ruby types inside of type specifier lists, as well as the other non-Ruby types that are accepted by convention in these lists.
It's important to realize that the conventions listed here may not always adequately describe every type signature, and is not meant to be a complete syntax. This is why the types specifier list is freeform and can contain any set of values. The conventions defined here are only conventions, and yard hash options they do not work for your type specifications, you can define your own appropriate conventions. Note that a types specifier list might also be used yard hash options non-Type values.
In this case, the tag documentation will describe what values are allowed within the type specifier yard hash options. Any Ruby type is allowed as a class or yard hash options type. Such a type is simply the name of the class or module. Note that one extra type that is accepted by convention is the Boolean type, which represents both the TrueClass and FalseClass types. This type does not exist in Ruby, however. In addition to basic types like String or ArrayYARD conventions allow for a "generics" like syntax to specify container objects or other parametrized types.
Multiple parametrized types can be listed, separated by commas. Note that parametrized types are yard hash options not order-dependent, in other words, yard hash options list of parametrized types can occur in any order inside of a type.
When the order matters, use "order-dependent lists", described below. Duck-types are allowed in type specifier lists, and are identified yard hash options method names beginning with the " " prefix. Typically, duck-types are recommended for param tags only, though they can be used in other tags if yard hash options. The following example shows yard hash options method that takes a parameter yard hash options any type that responds to the "read" method:.
In the latter case, KeyTypes or ValueTypes can also be a list of types separated by commas. An order dependent list is a set of types surrounded by " " and separated by commas.
This list must contain exactly those types in exactly the order specified. For instance, an Array containing a String, Fixnum and Hash in that order and having exactly those 3 elements would be listed as: Here is a non-exhaustive list of certain accepted literal values:. For instance, a method may copy all param tags from a given object using yard hash options reference tag syntax:. If a tag is specific to a given project, consider namespacing it by naming it in the form projectname.
Custom tags can be added to YARD either via the command-line or programmatically. The programmatic method is not discussed in this document, but rather in yard hash options TagsArch document. To add yard hash options custom tag via the command-line yard hash options. A few different options yard hash options available for the common tag syntaxes described above.
For example, to add a basic freeform tag, use:. Note that the tag title should follow the tag name with a colon: Other tag syntaxes exist, such as the type specifier list freeform tag --type-tagor a named key tag with types --type-name-tag.
If you want to create a tag but not display it in output it is only for programmatic useadd --hide-tag tagname after the definition:. This tag is transitive. If it is applied on a namespace module or classit will immediately be applied to all children objects of that namespace unless it is redefined on the child object. The special name api private does display a notice in documentation if it is listed, letting users know that the method is not to be used by external components.
Declares the API that the yard hash options belongs to. Any text is allowable in this tag, and there are no predefined values. Use the more powerful! Describe an options hash in a method. Yard hash options tag takes the name of the options parameter first, followed by optional types, the option key name, a default value for the key and a description of the option. The default value should be placed within parentheses and is optional can be omitted. Note that a param tag need not be defined for the options hash itself, though it is useful to do so for completeness.
Describe that your method can yard hash options used in various contexts with yard hash options parameters or return types. The first line should declare the new method signature, and the following indented tag data will be a new documentation string with its own tags adding metadata for such an overload. Documents a single method parameter either regular or keyword with a given name, type and optional description. This tag should only be used to mark objects private when Ruby visibility rules cannot do so.
Declares that the logical visibility of an object is private. In other words, it specifies that this method should be marked private but cannot due to Ruby's visibility restrictions. This exists for classes, modules and constants that do not obey Ruby's visibility rules.
This tag is meant to be used in conjunction with the --no-private command-line option, and is required to actually remove these objects from documentation output. If you simply want to set the API visibility of a method, you should look at the api tag instead. Describes that a method may raise a given exception, with an optional description of what it may mean. Describes the return value and type or types of a method.
You can list multiple return tags for a method in the yard hash options where a method has distinct return cases.
Accepts URLs or other code objects with an optional description at the end. Marks a TODO note in the object being documented. Yard hash options reference, objects with TODO items can be enumerated from the command line with a simple command:.