New function intro comment format for Rebol C source

[codebybrett]

A new commenting format is proposed for the Rebol C sources for which your acceptance is sought.

Example:

//
//  quit: native [
//  
//  {Stop evaluating and return control to command shell or calling script.}
//  
//      /with {Yield a result (mapped to an integer if given to shell)}
//      value [any-type!] "See: http://en.wikipedia.org/wiki/Exit_status"
//      /return "(deprecated synonym for /WITH)"
//      return-value
//  ]
// 
// While QUIT is implemented via a THROWN() value that bubbles up
// through the stack, it may not ultimately use the WORD! of QUIT
// as its /NAME when more specific values are allowed as names.
//
REBNATIVE(quit)
{

To see the effect of this in context with other functions see the draft conversions at: https://github.com/codebybrett/temporary.201508-source-format-change/tree/master/src

An introductory comment to a function declaration will contain rebol function metadata indented from slash by two spaces, a blank line, then any ordinary comments set off from double slash by a single space. Extra blank lines around the function description make easier reading.

Your opinions would be welcome in the chat room.

[hostilefork]

@zsx We are planning on going forward with this conversion pretty soon...right now I am trying to sort of tie up old unfinished branches just because it will be more of a pain to merge them later (every line being a conflict, we are doing the tab-to-spaces conversion here too...)

I don't know if that applies to anything you want to do before we do it. Let us know!

Git does have some abilities to ignore whitespace, I don't know much about how they work though.

[zsx]

I would like it to be more clear about what's comments taken by rebol and what's not. One space is not that obvious. What happened to "//;"? I think I liked it better. But I am OK with this, if that's what you guys agreed upon.

Thanks for the reminder, BTW.

[codebybrett]

The double newline after the rebol values separates the textual notes.

The parser test as currently written goes like this:

1. Gather rebol values while you have not hit a double newline sequence. E.g the 3 values:

   quit: native [...]

2. If the first rebol value gathered is a set-word! then we have validly formatted rebol metadata.

The spacing was thought to give a clean visual look, while minimising the length of lines, minimising special separators and highlighting function names.

Looking through the conversion I think this example may demonstrate your point, but I think in this case the notes should be manually reformatted to be clearer with the new format rather than change the format itself:

//
//  Check_Func_Spec: C
// 
// Check function spec of the form:
// 
// ["description" arg "notes" [type! type2! ...] /ref ...]
// 
// Throw an error for invalid values.
//
REBSER *Check_Func_Spec(REBSER *spec, REBYTE *exts)
{

[hostilefork]

I don't know how often putting comments in the header will be necessary, as I feel the native spec itself being in the comment...and generating the code...is about the best "comment" on a native definition we could ask for.

Most implementation comments are probably fine in the body. So maybe what we do is lean that direction, to make native comments just the native definition most of the time. That gives a good separation.

//
//  quit: native [
//  
//  {Stop evaluating and return control to command shell or calling script.}
//  
//      /with {Yield a result (mapped to an integer if given to shell)}
//      value [any-type!] "See: http://en.wikipedia.org/wiki/Exit_status"
//      /return "(deprecated synonym for /WITH)"
//      return-value
//  ]
// 
REBNATIVE(quit)
{
    // While QUIT is implemented via a THROWN() value that bubbles up
    // through the stack, it may not ultimately use the WORD! of QUIT
    // as its /NAME when more specific values are allowed as names.

How about that for the natives? I don't know what I think of it, but I like it better than (for instance) adding two more vertical lines of space and a --- divider, or something space-eating like that.

[zsx]

I think I like this one. This makes the comment more for the implementation rather than the native interface.

[hostilefork]

@zsx Okay, well it does work for natives but with regular functions that will be maybe a bit strange. So like:

//
//  Push_Trap_Helper: c
//
void Push_Trap_Helper(REBOL_STATE *s) {
    // Used by both TRY and TRY_ANY, whose differentiation comes
    // from how they react to HALT.

Which isn't actually that bad either, I guess, if we start thinking that comment before is all metadata and is Rebol loadable. It's fairly stylized but stylized in a semi-meaningful way. Maybe I could get used to that.

The thing I am a broken record about is "modify with confidence" so it's not like just because we run the converter means we're stuck with it forever... Brett tackled this in a fairly generic way and if there turns out to be friction it can be modified.

[hostilefork]

@zsx @codebybrett I have essentially gotten everything ready to where I have no large pending commits to get out. If a call can be made on this issue of where to put the comments I'd be ready.

My suggestion is to split it down the middle and keep the current ability to use the format as designed, but in the case of natives in particular use a convention that the implementation documentation be in the body. So for the Push_Trap_Helper: c example, do not put the comments in the body.

Again--keep the format able to process it either way.

[codebybrett]

On this basis, there's no need to change the existing parser for the build process. So I've modified the conversion script to generate this suggestion. Please see the commit for the updated draft . Perhaps n-control.c is a good example of this change.

[hostilefork]

I'm ready to sign off on Brett's compromise if you are, @zsx.

Also, your concerns won on the errors. I deleted my trick, used parentheses for the macros, and now they are very nice. :-)

[zsx]

When I give it another look, the following looks better to me, and it's more aligned with the format in src/os/, e.g. https://github.com/metaeducation/ren-c/blob/master/src/os/posix/host-library.c

Putting the comment after "{" makes it more "local" (pertinent to the code following it) rather than "global" (pertinent to the whole function).

//
//  quit: native [
//  
//  {Stop evaluating and return control to command shell or calling script.}
//  
//      /with {Yield a result (mapped to an integer if given to shell)}
//      value [any-type!] "See: http://en.wikipedia.org/wiki/Exit_status"
//      /return "(deprecated synonym for /WITH)"
//      return-value
//  ]
// 
REBNATIVE(quit)
//  
//  While QUIT is implemented via a THROWN() value that bubbles up
//  through the stack, it may not ultimately use the WORD! of QUIT
//  as its /NAME when more specific values are allowed as names.
{

[hostilefork]

@zsx Hmmm.... I see your point. It's unusual but so is everything else we're doing.

Our tab point hack is lost here, though I do agree that it looks pretty good... but we're not going to start indenting all our // comments to a tab point. I was suggesting we only do tab points on code.

[hostilefork]

@zsx Or, to put that another way, would you accept:

//
//  quit: native [
//  
//  {Stop evaluating and return control to command shell or calling script.}
//  
//      /with {Yield a result (mapped to an integer if given to shell)}
//      value [any-type!] "See: http://en.wikipedia.org/wiki/Exit_status"
//      /return "(deprecated synonym for /WITH)"
//      return-value
//  ]
// 
REBNATIVE(quit)
//  
// While QUIT is implemented via a THROWN() value that bubbles up
// through the stack, it may not ultimately use the WORD! of QUIT
// as its /NAME when more specific values are allowed as names.
{

I guess I just want to avoid the slippery slope of indenting one's day to day comments on tab points, because...why? The tab point is because you want to align with another tab point in the ensuing information.

[zsx]

Yes, I am OK with this one.

[hostilefork]

@codebybrett Okay, I can work with that if @zsx says yea. :-) Whenever you're ready.

Death to tabs!

[codebybrett]

Conversion of comments and tabs applied in https://github.com/codebybrett/ren-c/tree/20151117-source-conversion

[hostilefork]

Now in master!

metaeducation@e6172c2