lsegal/yard — Issue #443: Documenting constants defined from C code with rb_define_const()
Author: avsej
Created: 2012-01-03 12:13:38+00:00
State: open

Here is the `handle_constants` method from [c_parser.rb][1]

```ruby
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:

```c
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.

[1]: https://github.com/lsegal/yard/blob/372cd66ef95f008cc1e0ad25ade35d58911c20c2/lib/yard/parser/c_parser.rb#L157