yard

yard copied to clipboard

I'm documenting this Ruby C extension. It's a binding for my Z80 emulator. Since YARD doesn't work very well with C files, I followed the advice given in previous issues (#1281 and #1436) and I placed all doc into the .rb files. For example, this documents a method of the Z80 class:

class Z80
  ##
  # @!method execute(cycles)
  # Runs the emulation for a given number of clock +cycles+, executing
  # only instructions without responding to interrupts.
  #
  # @param cycles [Integer] Number of clock cycles to be emulated.
  # @return [Integer] The actual number of clock cycles emulated.
  #
  # @see https://zxe.io/software/Z80/documentation/latest/APIReference.html#c.z80_execute
  #   <tt>z80_execute()</tt>
end

The question is: how do I do the same for constants? for example, I need to document this one: Z80::MAXIMUM_CYCLES_PER_STEP

This constant is defined in a .c file as follows:

rb_define_const(klass, "MAXIMUM_CYCLES_PER_STEP", UINT2NUM(Z80_MAXIMUM_CYCLES_PER_STEP));

Using this doesn't work:

class Z80
  ##
  # Maximum number of clock cycles that {#run} and #{execute} can emulate.
  # @!parse [c]
  # void Init_z80(void) {
  #     rb_define_const(klass, "MAXIMUM_CYCLES_PER_STEP", UINT2NUM(Z80_MAXIMUM_CYCLES_PER_STEP));
  # }
end

It would be great to be able to use something like this:

class Z80
  ##
  # @!constant MAXIMUM_CYCLES_PER_STEP
  # Maximum number of clock cycles that {#run} and #{execute} can emulate.
end