I also started a stub wiki page about chicken.h ( https://wiki.call-cc.org/notes-on-chicken.h), but I agree that commenting its source code is a much better solution.
Best wishes, Arthur 2014-07-06 17:02 GMT-03:00 Arthur Maciel <[email protected]>: > Now with correct subject. Sorry. > > Date: Sat, 05 Jul 2014 23:31:18 +0200 (CEST) > > From: Felix Winkelmann <[email protected]> >> > > More documentation for internals, even comments will do. >> >> >> Well, that can be done. External documentation will quickly get out of >> sync, but comments shouldn't be a problem. If there are particular >> places where one could start, please tell. >> > > Probably all my doubts are due to my ignorance about C and computer > internals, but I would love to understand more the chicken.h file. > ( > http://code.call-cc.org/cgi-bin/gitweb.cgi?p=chicken-core.git;a=blob;f=chicken.h;h=f5a103ee14314f7c679e01dd8e11c0404043791a;hb=HEAD > ) > > I feel really ashamed to ask this, but as I want to contribute more to > Chicken, it would help me a lot to know about these details: > - Throughout the whole file I can't guess what is the meaning of some > prefix or suffix letters in function names, like: > - C_truep(x): I suppose the "p" stands for "predicate" as in Common > Lisp, right? > - C_c_pointer(x): what does the "_c_" stand for? > - C_c_pointer_nn(x): what about "nn"? > - C_fixnum_plus(n1, n2) vs. C_u_fixnum_plus(n1, n2): does the "_u_" on > the second mean "unsigned"? > - C_ub_i_flonum_plus(x, y): what about "ub"? unsigned byte? > - C_a_i_flonum_plus(ptr, c, n1, n2) and C_a_i(a, n): what about "a" > and "i"? > - C_mpointer: the "m" stands for "memory"? > - C_mk_bool: "mk" stand for "make"? > - Lines 777 to 838: I suppose the code is used for CPS, but I'm not sure > about it and I can't figure out why it is implemented that way and how it > is used in practice. > - Lines 876 to 909: although this excerpt starts with a comment about > Clang and G++ limitations on statement expressions, all the hackery is only > implemented when DEBUGBUILD is defined. I don't understand why. I also > can't understand the code from 892 to 909, but I suppose I need more C > knowledge to that. > > I thought about comments like this in chicken.h: > /* "p" suffix (like in C_truep) stands for "predicate" as in Lisp > tradition. See: http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node69.html > */ > > The CPS and statement expressions could be elsewhere. > > What do you think? Is it worthy? > > Thanks for help and sorry about the ignorance. > > Best wishes, > Arthur > >
_______________________________________________ Chicken-hackers mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/chicken-hackers
