Documenting constants defined from C code with rb_define_const()

[avsej]

Here is the handle_constants method from c_parser.rb

def handle_constants(type, var_name, const_name, definition)
  namespace = lookup_var(var_name)
  ensure_loaded!(namespace)
  obj = CodeObjects::ConstantObject.new(namespace, const_name)
  obj.value = definition
  obj.add_file(@file)
  obj.source_type = :c
  comment = find_constant_docstring(obj, type, const_name)

  # In the case of rb_define_const, the definition and comment are in
  # "/* definition: comment */" form.  The literal ':' and '\' characters
  # can be escaped with a backslash.
  if type.downcase == 'const'
    elements = comment.split(':')
    new_definition = elements[0..-2].join(':')
    if new_definition.empty? then # Default to literal C definition
      new_definition = definition
    else
      new_definition.gsub!("\:", ":")
      new_definition.gsub!("\\", '\\')
    end
    new_definition.sub!(/\A(\s+)/, '')
    comment = $1.nil? ? elements.last : "#{$1}#{elements.last.lstrip}"
  end

  obj.docstring = comment
end

What the use of new_definition variable? I'm trying build documentation for following code:

rb_define_const(cBucket, "FMT_MASK", INT2FIX(FMT_MASK));

Is it possible to hide C macro in the documentation and use the actual value? For example I know that the value will be Fixnum 0x3. How can I state it? If I put C comment before rb_define_const it will just add docstring but the macro INT2FIX(FMT_MASK) still in the doc and it meaningless for library users.

Thanks.

[lsegal]

The syntax would be /* 0x3: some comment about this constant */ as described in that ruby comment in the code. I assume it goes on the same line as the const definition. Note that this is the same syntax as RDoc.

[avsej]

It doesn't work when I put the comment on the same line like this:

rb_define_const(cBucket, "FMT_MASK", INT2FIX(FMT_MASK)); /* 0x3: Bitmask for flag bits responsible for format */

When I put the comment before declaration, it store it as docstring and show macro as a value in the HTML (see screenshot)

/* 0x3:  Bitmask for flag bits responsible for format */
rb_define_const(cBucket, "FMT_MASK", INT2FIX(FMT_MASK));

Seems like code with new_definition variable tries to do something, but I cannot see how it uses this variable

[lsegal]

Looks like we don't change the object.value in the case where it finds that constant docstring. Should be an easy fix, though.

[lsegal]

This was fixed with the new C parser in 0.8.0