CODEWITHSUNDEEP
rubymethodsyard
Johannes Grassler
Johannes Grassler

Reputation: 21

Documenting methods in top-level namespace with YARD

I documented some Ruby code using YARD and I am having trouble getting the YARD documentation I created for some methods in top-level name space to show up in yardoc's HTML output.

My documentation looks essentially the same as the YARD gem's own in lib/yard/globals.rb, with the addition of an @api tag. I did try removing it, and ran yardoc without the --api parameter but that didn't help matters.

This is an example:

#!/usr/bin/ruby

# @group PIP Negotiation: Backend and helper methods
#
# Deserializes a topology graph in YAML format into the database.
#
# @api pip-negotiate
# @param [String] graph A FleRD graph in YAML format
# @return [Boolean] status True if graph was deserialized successfully, False otherwise.
# @return [Integer] gl_id The database ID of the deserialized GraphLabel (nil if deserialization failed).
# @return [Array] output Standard output channel of flerd-deserialize.rb(1)
# @return [Array] output Standard error channel of flerd-deserialize.rb(1)

def insert_graph(graph)
  return [ true, 1, ["1"], [""] ]  # Not the actual method body.
end

# @endgroup

When I run yardoc to generate the HTML documentation everything looks fine at first:

% yardoc -o pip-negotiate --api pip-negotiate '**/*.rb'                  
Files:           1
Modules:         0 (    0 undocumented)
Classes:         0 (    0 undocumented)
Constants:       0 (    0 undocumented)
Methods:         1 (    0 undocumented)
 100.00% documented
%

The generated HTML does not contain any of my documentation though. All it contains is a list of methods with the pip-negotiate API tag. You can see for yourself here:

http://btw23.de/tmp/pip-negotiate/api/method_list.html

What I expected instead was something more like YARD's own documentation on top-level methods:

http://rubydoc.info/gems/yard/toplevel

Is there perhaps any special magic I am missing in my yardoc invocation?

My yardoc version is 0.8.6.2, running on Ruby 1.8.7 (2012-06-29 patchlevel 370) [x86_64-linux]

Upvotes: 1

Views: 2228

Answers (2)

Johannes Grassler
Johannes Grassler

Reputation: 21

The presence or absence of --api doesn't seem to make a difference. Both with and without the equals sign the --api option causes none of the method documentation to show up. It does work in other cases, no matter the equals sign; I've been using it a lot to compartmentalize documentation on a bunch of instance methods that are not in top-level namespace. I believe I have found the reason now.

Apparently the @api tag is somewhat namespace sensitive, and in a peculiar way. Consider this example:

#!/usr/bin/ruby

# @api pip-negotiate

class Foo

# Deserializes a topology graph in YAML format into the database.
#
# @param [String] graph A FleRD graph in YAML format
# @return [Boolean] status True if graph was deserialized successfully, False otherwise.
# @return [Integer] gl_id The database of the deserialized GraphLabel (nil if deserialization failed).
# @return [Array] output Standard output of flerd-deserialize.rb(1)

def insert_graph(graph)
  return true, 1, ["1"], [""]  # Not the actual method body.
end

end

With either of these two yardoc invocations it will render the method documentation for insert_graph() fine:

% yardoc -o pip-negotiate --api=pip-negotiate '**/*.rb'
% yardoc -o pip-negotiate --api pip-negotiate '**/*.rb'

But if we move the @api tag down to the method it will break things:

#!/usr/bin/ruby

class Foo

# Deserializes a topology graph in YAML format into the database.
#
# @param [String] graph A FleRD graph in YAML format
# @return [Boolean] status True if graph was deserialized successfully, False otherwise.
# @return [Integer] gl_id The database of the deserialized GraphLabel (nil if deserialization failed).
# @return [Array] output Standard output of flerd-deserialize.rb(1)
# @api pip-negotiate

def insert_graph(graph)
  return true, 1, ["1"], [""]  # Not the actual method body.
end

end

No matter the yardoc invocation, the method documentation is ignored, but the method gets listed. My hypothesis, since I don't have the spare cycles to verify it from YARD's source, is that there needs to be an unbroken chain of @api tags from the outermost taggable namespace, which would be the Foo class in this example. And so far I haven't found a way to tag the top-level namespace, helpful though that would be.

That being said, the comment on --api breaking things got me on the right track: While the method documentation still doesn't show up in the method list if I omit the --api parameter, it does show up in the class list of all places (under "Top Level Namespace"). That's why it eluded me the first time I tried omitting the --api parameter.

I'll try to work with the YARD formatter to keep the method list from being displayed, so it doesn't confuse my users as it confused me, and try to compartmentalize my documentation/refactor my code such that I don't require multiple @api tags in any given file.

Upvotes: 1

Neil Slater
Neil Slater

Reputation: 27207

The correct syntax appears to be:

yardoc -o pip-negotiate --api=pip-negotiate '**/*.rb'

The equals sign is apparently needed for the --api option to work correctly. I suspect otherwise the name pip-negotiate was being used as an input file name to parse for documentation.

Upvotes: 0

Related Questions