Specifying Types

[trans]

One of the nice things about YARD is the ability to specifically denote the types of parameters and return values. Of course with Ruby and duck-typing that's not exact, but it helps give a general idea of purpose. So for instance you might have:

  # @param [String] name
  # @return [String] name upcased
  def upcase(name)
    name.upcase
  end

How might this be done in Tomdoc?

[tombell]

If you read the spec http://tomdoc.org/ you'll see that arguments and returns specifically state the type they're returning, for example: # host - The String hostname to bind (default: '0.0.0.0'). and # Returns the duplicated String.. The thing about tomdoc is that it's not meant to be parsed by some application to generate docs, it's suppose to be "human readable" hence it's plain English, not some fancy documenting syntax.

[trans]

I think it can do both. Otherwise why have a strict format at all? Just throw in a markup language and be done with it (which is how rdoc did things).

A solution might be as simple and unobtrusive as:

# Connect to host.
#
# host - The ::String hostname to bind (default: '0.0.0.0').
#
# Returns the duplicated ::String.
def connect(host)
   ...
end

On the other hand, maybe we could do something like:

# Connect to host.
#
# host - The String hostname to bind (default: '0.0.0.0').
#
# Returns the duplicated String.
def connect(host)  #(String)
   ...
end

Or something like that.

[tombell]

You're free to do that in your comments, but I doubt it will become part of a spec as it goes against the point of the spec.

[trans]

The devil is of course in the implementation ;-) Currently I think yard-tomdoc plugin looks for /\[[A-Z].*?\]/, or there abouts, and assumes the match to be types.

Just thought Tomdoc might be better off to define a standard.

[leejarvis]

-1 on ::String and # (String) -- I'm with @tombell and the current spec on this one, and I don't think it should change to be more 'computer readable' for types

[trans]

Please discuss. Just "-1"ing doesn't explicate the idea. The problem I see with not having some standard is that it will lead to different incompatible workarounds by tomdoc->documentation implementations.

[mojombo]

I don't really see a need to denote types with a special syntax. The biggest thing is to just state what the type(s) are. That's 99% of the battle. The other 1%, being able to automatically detect and link those in an automated docs generator, can be done by heuristics or just ignored. I don't think the readability hit caused by special syntax is worth it.