Improving crystal docs for C bindings

[Heaven31415]

Right now as far as I can see, crystal docs tool won't help you in any way if you are creating a binding to some C library. It isn't possible to document fun declarations with markdown comments, which I think might be beneficial.

Would you consider adding support for documentation comments for fun declarations and other things related to bindings like C structs and enums?

[asterite]

You shouldn't document those (at least from an API point of view) because you are not supposed to directly expose them. You should wrap them with Crystal constructs, and document those.

[straight-shoota]

@asterite But sometimes it makes sense to expose parts of the C bindings (for example structs) in the public API to ensure interoperability with other other C libraries. See Socket::Address for example.

Enums in lib definitions can already be documented, by the way. The documentation from the lib enum will be used when it is aliased as Crystal type.

[Heaven31415]

I agree with @straight-shoota. I'm currently working on a GLFW wrapper, which happens to have support for creating Vulkan objects and wrapping them into anything doesn't make any sense, because those functions were designed to by directly used by Vulkan API. That's why I want to have some kind of documentation for lib functions.

[RX14]

It's rare that a wrapped object will have no methods. In that case you have two options:

• you can just wrap it anyway and add no methods to it - the object is only consumed by other objects.
• you can use the @[Extern] annotation to create a crystal struct which can be documented but also used directly in lib bindings.

[sol-vin]

You shouldn't document those (at least from an API point of view) because you are not supposed to directly expose them. You should wrap them with Crystal constructs, and document those.

I would be fine with this if macros worked for lib but they don't. Why should someone have to write out potentially hundreds of functions to wrap them? lib methods need a special "LibMethod" type in Macros that has the Crystal method name, C function name, args, and return type.

[asterite]

That's already the case. The only issue is that because of some semantic intricacies, they are only accessible inside methods:

def foo
  {% p LibC.class.methods %}
end

foo

[straight-shoota]

@sol-vin That's a related topic, but a different issue. I created #12395 to track that.

[sol-vin]

I'd like to bring attention to this issue again if possible. I'd really love this as a feature. Maybe being a flag like crystal docs --output-lib. Potentially also an argument for what lib/libs should be output like crystal docs --output-lib Raylib.

[nobodywasishere]

I think this could work well if combined with #13184 if the C Lib stuff is put in a separate tab.