Yard parser

Parsers

YARD, from the way I understand it, uses a system of parsers to process all the files that eventually outputs into documentation. A parser is registered for each file type. By default YARD is equipped with the ability to process ruby files so if you are looking for code already tucked away in ruby (like a DSL that you have created) source, it's already there and so you can skip the registering a parser and move straight on to creating a YARD Handler. If you want to parse different files, then this section will attempt to do its best to provide you with that knowledge.

A quick aside, I tend to learn better in situations where I see the work; not just seeing the solution set. So this tutorial will likely take some very rudimentary steps that may execute code before it's complete generating error messages. This personally helps me learn more and provides assistance with troubleshooting problems that crop up. For example, if I make a simple mistake with a earlier step of the process but don't catch it until later on in another context; I will often spend misappropriated time hunting down issues with the current step when the problem occurred at a much earlier point.

• Getting YARD to recognize you
• Registering your parser
• Creating your stub parser
• Giving your stub parser a skeleton

Getting YARD to recognize you

Before getting started with creating a parser it is fundamental that we get YARD's attention. What I love more than anything is validation and feedback, so it is important to me that that I am positive YARD is ready to listen to the work that I about to start doing.

On the command line YARD makes available an option, -e OR --load that allows you to specify a script file that is loaded before any source file is parsed. This is where we are going to start:

yard -e extensions.rb
[error]: The file `extensions.rb' could not be loaded, check the path and try again.

Upon execution of the command yard -e extensions.rb you should see the following error message and that's great because we haven't created the file. This is the file that we are going to use to define our parser (and likely our handlers and some other objects) so name it something you feel is appropriate for your project, source, or package. I will continue to refer to it as extensions.rb. You might also take this moment to create a batch file or rake file to allow you to execute this command again and again. I will keep repeating yard -e extensions.rb here in the documentation to ensure it remains clear what is taking place.

So I created a extensions.rb that contains:

  puts "YARD SEE ME"

So when I execute the same command again I should see:

yard -e extensions.rb
YARD SEE ME
Files:           0
Modules:         0 (    0 undocumented)
Classes:         0 (    0 undocumented)
Constants:       0 (    0 undocumented)
Methods:         0 (    0 undocumented)
 NaN% documented

YARD recognized the file that you specified and executed it before it parsed 0 files. This, while seemingly mundane is, as I said, fundamental to getting started with integration with YARD.

Registering your Parser

When you register a parser you specify a symbol name, the parser class, and the file extension.

Creating your stub Parser

With a parser registered and YARD failing, until we get the work done, it is now time to implement a stub parser. The end product will be a parser that will log that it has seen the file it is suppose to see.

Giving your stub parser a skeleton

YARD is giving our parser the files we want. Now it is our job to start turning the data into code objects that YARD can utilize and start display for us.

Conclusion

At this your parser should be able to accept a file, process it, and return to YARD the contents of the file. We are not done yet, but we're almost there. The next step is creating a Handler or handlers for the various objects within the files.