Get doc of simple extern methods from the wrapped C functions

[xymus]

For simple functions, such as make_current in:

extern class EGLDisplay ...
    fun make_current(draw, read: EGLSurface, context: EGLContext): Bool `{
        return eglMakeCurrent(recv, draw, read, context);
    `}
...
end

The doc in Nit would be pretty much the same thing as the doc in the C version. The official doc is pretty long: https://www.khronos.org/registry/egl/sdk/docs/man/html/eglMakeCurrent.xhtml Using an abstract in Nit would lose information, and copying it over could cause a desynchronisation in the long term. (Not so much for Khronos APIs but for other libraries it is a real problem.)

The solution would be to link the documentations together, in an automated way as much as possible. nitdoc could then generate an enriched doc, with maybe a link to the corresponding doc of the C API and extracting a synopsys when possible!

I would propose something like this:

# foreign_documentation: https://www.khronos.org/registry/egl/sdk/docs/man/html/*.xhtml
module egl

extern class EGLDisplay
    # Here the doc is infered from the single C function in the C implementation.
    # It could also be declared with:
    # foreign_feature: eglMakeCurrent
    fun make_current(draw, read: EGLSurface, context: EGLContext): Bool `{
        return eglMakeCurrent(recv, draw, read, context);
    `}
...
end

[xymus]

Extern classes could be documented in the same way. The foreign type can easily be extracted from an extern class declaration. In C, it's either { SomeStructure * `}` or { OpaquePointer }.

[Morriar]

+1, bonne idée