Support for C

[beoran]

It would be nice if the spec was extended to support C, for c extensions to ruby. Other programming languages could also benefit. Probably it would look something like this:

/* Public: Add two integers together
*
* one  - The int to be added
* two - The int to be added
*
* Examples
*
*   add(3, 4)
*   // 7
*
* Returns the sum of the two integers as an int.
*/
int add(int one, int two) {
  return one + two;
}

[drbrain]

Changing the wording about # to 'appropriate comment marker' would make this spec-compliant, but it should already work in RDoc master. (But for a :markup: magic comment at the top, --markup or using a directive will work)

[sarahhodne]

Well, technically it says "TomDoc for a specific method consists of a block of single comment markers that appears directly above the method." It adds "#" in brackets, but I think the text is what counts.

Besides, I think you should use // instead of /* and */ to avoid the "blank" line between the comments and the function definition (which shouldn't be there according to the spec). So this is what I think looks better:

// Public: Add two integers together.
//
// one - The int addend.
// two - The int addend.
//
// Examples
//
//   add(3, 4)
//   // => 7
//
// Returns the sum of the two integers as an int.
int add(int one, int two) {
  return one + two;
}

[drbrain]

// is not a valid C comment for all of the compilers ruby is built on.

[sarahhodne]

I thought Ruby was built according to C99?

[drbrain]

C90: http://redmine.ruby-lang.org/projects/ruby/wiki/DeveloperHowto

[sarahhodne]

Ah, I see.

I think my personal preference would be this, then:

/* Public: Add two integers together.
 *
 * one - The int addend.
 * two - The int addend.
 *
 * Examples
 *
 *   add(3, 4);
 *   // => 7
 *
 * Returns the sum of the two integers as an int. */
int add(int one, int two) {
  return one + two;
}

But, as I said, that's personal preference. The spec says not to leave a line blank between the Returns statement and the function declaration, and even though */ technically isn't a blank line, it looks like it to me.