Warns about @api values but Yardoc says it is freeform

[gioele]

Yardstick produces warnings like

The @api tag must be either public, semipublic or private

but the the Yardoc guide says

@api: Declares the API that the object belongs to. Does not display in output, but useful for performing queries (yardoc --query). Any text is allowable in this tag, and there are no predefined values(*).

@api freeform text

(*) Note that 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.

At the same time, wouldn't it be better to suggest @private instead of @api private?

[sarahhodne]

I believe yardstick is pretty opinionated. It warns about having a period at the end of the first line of the method description, but I don't think that's specified in the YARD documentation at all. Same thing about the first "line" of the method description spanning over several lines not being allowed.

[gioele]

Looking at the code, I see that rules are specified as

rule 'The @api tag must be either public, semipublic or private' do
  %w[ public semipublic private ].include?(tag_text('api'))
end

Maybe it would be possible to make these rule identifiable and provide ways to enable/disable them.

rule 'The @api tag must be either public, semipublic or private', :api_tag_content do
  %w[ public semipublic private ].include?(tag_text('api'))
end

$ yardstick --ignore api_tag_content .

[sarahhodne]

Or you could just ignore them in the output. These are only guidelines, and like any other kind of code metrics they can (and in some cases should) be ignored.

[gioele]

Indeed now I ignore them with a grep -v. But I miss the ability to have yardstick write out stats about how much the code is documented.

[dkubb]

Sorry for taking so long to reply to this. I think I'm going to leave in the API specification. It may be optional in YARD, but I think it's important information and I probably won't filter it out. If you wanted to supply a patch I might reconsider it, but I don't need it and so far there's only been one request for it, so I'll probably defer it for now.

[aaronmallen]

@dkubb could you point me to a definition for these values, or add them to the documentation? public and private are pretty apparent however what is semipublic.