C API documentation #2959
C API documentation #2959
Conversation
|
Looks good. But this pull-request has several conceptual changes in one. Next time, could you separate pull-requests for each concept (and gain more contribution measurement)? |
|
Hi @sagmor, this is great work. I did some time ago work on the mrbdoc tool and we integrated it into the official website (https://github.com/mruby/mruby.github.io/blob/master/gen_mrbdoc.rb). Your generated stuff looks much better and I would encourage you (of course only if you have time and fun) to consider a pull request to exchange the mrbdoc integration in the mruby.github.io repo [https://github.com/mruby/mruby.github.io] with your variant. In this way we can keep the documentation via your tool up-to-date on the official website. |
|
Why do we need |
|
I guess that:
|
|
Should probably be named |
|
The problem is that MRB_API ( |
|
As @takahashim says, inline functions keeps the fact that It's a function without masking it under a "constant" that makes a lot easier to document C Headers consistently (all while keeping the performance of the Right now I'm playing with that fact to further improve the docs with a yard plugin it's a bit early yet but here's a demo of it's current state when executed on MRuby's core |
Let me rephrase my question: what's the rationale behind the introduction of
That's great! (I like yard.) |
|
@cremno Actually I took the inspiration from libgit2 and to be honest I will make a few experiments defining And by the way, The docs are getting better (See: sagmor.com/mruby) |
|
http://www.greenend.org.uk/rjk/tech/inline.html is a good explanation. I think the linked libgit2 code is a bit too cautious. I don't know its history though. Maybe there was a reason to define it that way. However mruby already provides |
|
@cremno Further investigating I found out there's an
But I don't have enough info to make an informed choice. 1:
#define mrb_foo /* code */
/*
* What we have now, fast and easy.
* but in a way inconsistent (for documentation purposes)
*/
2:
#define MRB_INLINE static inline __attribute__((always_inline))
MRB_INLINE void mrb_foo( void ) { /* code */ }
/*
* We turn the define into a function and get more context for the documentation
*/
3:
static inline void mrb_foo( void ) { /* code */ }
/*
* Pretty much the same as above.
* Not sure if the __attribute__ has a real impact, and the need of a
* MRB_INLINE define seems like a keyword to keep it visually consistent with MRB_API
*/
4:
#define mrb_inline inline __attribute__((always_inline))
MRB_API mrb_inline void mrb_foo( void ); /* and code goes on some .c file */
/*
* I like how this looks.
* mrb_inline is consistent with other "flags" like mrb_deprecated or mrb_noreturn
* but it forces the function's code to live on a different .c file. Which means more
* work but also means the implementation get's hidden/encapsulated
*/From how it looks, I like the fourth option but I have no idea if there's a real performance difference on each option and how far we should move to replace those |
I started to work on documenting MRuby's C API.
While working on a gem project, I started to get locked quite often on "whats the function that does x?" moments so I started to document the methods I found on the process.
I noticed there are some methods already documented at doc/api but I believe it's better to have the API documented on the headers, so I've been taking those docs, and merging them into the headers as well.
I'm leaving this pull request to get some feedback before putting more effort into it.
Some of the things I've experimented with related with documenting MRuby's C API are:
mruby.org/c-apifor example.MRB_API,mrb_deprecatedand moved them tomruby/common.hMRB_BEGIN_DECLandMRB_END_DECLto get rid of those uglyextern "C"all over the headers.#definealiases with inline function, this is just an experiment/proposal, they look more consistent while documenting (see mrb_class_new_instance)As I said, I'm leaving this here to see what you think of these approaches before putting more effort into them.