Re: [Chicken-hackers] [PATCH] Fix #1133

[Arthur Maciel]

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 <address@hidden>:

Now with correct subject. Sorry.

Date: Sat, 05 Jul 2014 23:31:18 +0200 (CEST)

From: Felix Winkelmann <address@hidden>

> 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