Closed GinoGiotto closed 1 year ago
- Comments with
/*!***/
: They seem to have a special type of formatting, which is consistent with some C files I came across that were not created by Norm. Specifically, I looked atmmfatl.c
by @wlammen andmmtest.c
by @digama0, both of which have comments already updated in the//
form, except for the/*!***/
ones, so they seem to be intentionally built this way.
These are doxygen comments. I think doxygen supports a variety of styles but if you want to be sure you haven't broken anything you should test using ./build.sh -d
.
The other 3 categories sound fine.
Continuation of #138.
As I was viewing the code, I noticed certain types of comments that I may not be supposed to edit, so I chose to omit them. These comments can be categorized into four groups:
Comments with
/*!***/
: They seem to have a special type of formatting, which is consistent with some C files I came across that were not created by Norm. Specifically, I looked atmmfatl.c
by @wlammen andmmtest.c
by @digama0, both of which have comments already updated in the//
form, except for the/*!***/
ones, so they seem to be intentionally built this way.Comments that have multiple
***
: It appears that they are intended to be noticeable, for example like the header that is present at the beginning of every file:Or like the following comment:
So I left those out too (the header has the same formatting in the already updated
mmfatl.c
mmtest.c
files too).Comments that are inside the code: These are probably the most uncontroversial ones since they wouldn't work with
//
, unless with some rewrapping of the code itself. Example:Technically the comment
/* lo r */
isn't strictly between coding characters, so it could be edited with// lo r
, but it's clearly of the same type of the neighbouring ones, so I left it out too.Multiline commented out C code: It appears that it was intended to be easily uncommented for experimental use. Since line comments would be less practical for this purpose, I left the original block ones. Example:
int main(void) { vstring_def(s); vstring_def(t);
printf("Hello\n"); let(&t,edit(" x y z ",2)); let(&s,cat(right("abc",2),left("def",len(right("xxx",2))),"ghi",t,NULL)); printf("%s\n",s); printf("num %s\n",num(5)); printf("str %s\n",str(5.02)); printf("num1 %s\n",num1(5.02)); printf("time %s\n",time()); printf("date %s\n",date()); printf("val %f\n",val("6.77")); }
*/ In general my convention knowledge for C is very limited, so I built these criteria by intuition. Let me know if you agree with these criteria or if there are some standards that you are aware of.