RDoc parser format

Hello Anders,

I would like to know how RubyMine parses the rdoc comments in my source code.

The code below inserts a Usage: and a Description: heading

Is there somewhere I can find the documentation for how this works.

Regards
Anders

# Reads a user setting without throwing an exception, returns nil or default value.
#
#   user_setting 'jetty.home', '/home/jetty/jetty-distribution-7.0.1.v20091125'
#   user_setting 'jetty.home'
#
#     name_path:: The path to the parameter separated by dots (.)
#     default::   A default value if the parameter given by the path does not exist.
#
def user_setting name_path, default=nil
  names = name_path.split "."
  settings = Buildr.settings.user
  begin
    names.each do |name|
      settings = settings[name]
    end
    return default if settings.nil?
    settings
  rescue
    default
  end
end

RubyMine tries to extract possible return types from comments , however in this particular case no type annotation can be found.
Maybe you should ask more specific question?

Regards,
Oleg

I was referring to the popup that RubyMine displays for the code.
I'm sorry if I wasn't clear enough.


The code above is rendered like above, and I would like to know how the Usage and Descriptions parts are
parsed out of the text. Is there a format RubyMine expects?

Hi Anders,

RubyMine uses standart ruby comments call-seq formatting policy to generate help.
It is assumed that usage is indented with 3 spaces in comment, when description has other indent.

Regards,
Oleg

Hi again Oleg,

And thanks again for taking the time to reply.

I still don't get it though . All I can get out of the documentation is that text that is indented
is to be treated as verbatim. I find nothing that gives descriptions of this text.

Anyway I have decided to use the following documentation format (that does not generate any automatic label)

#
# Reads (possibly nested) user settings, returns +default+ if +name_path+ is not found.
#
# * +name_path+ The path to the parameter separated by dots (.)
# * +default+   A default value if the parameter given by the path does not exist.
#
# === Examples
#
#   user_setting 'jetty.home', '/home/jetty/jetty-distribution-7.0.1.v20091125'
#   user_setting 'jetty.home'
#
def user_setting name_path, default=nil
  names = name_path.split "."
  settings = Buildr.settings.user
  begin
    names.each do |name|
      settings = settings[name]
    end
    return default if settings.nil?
    settings
  rescue
    default
  end
end

It produces the following output which understand completely:


And again.

Thanks for your time.
Anders

Here you can find some useful information on help formatting: http://www.jetbrains.net/confluence/display/RUBYDEV/Ruby+documentation+markup+spec

Ok, thanks!