metamath / metamath-exe

Metamath program - source code for the Metamath executable
GNU General Public License v2.0
75 stars 25 forks source link

Line comments instead of block comments 2 #139

Closed GinoGiotto closed 1 year ago

GinoGiotto commented 1 year ago

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:

  1. 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 at mmfatl.c by @wlammen and mmtest.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.

  2. 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:

    /*****************************************************************************/
    /*        Copyright (C) 2018  NORMAN MEGILL                                  */
    /*            License terms:  GNU General Public License                     */
    /*****************************************************************************/
    /*34567890123456 (79-character line to adjust editor window) 2345678901234567*/

    Or like the following comment:

     /*** See the comments in mmvstr.h for an explanation of these functions ******/ 

    So I left those out too (the header has the same formatting in the already updated mmfatl.c mmtest.c files too).

  3. 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:

     if (graphicsChar == 218 /* up left */ || graphicsChar == 217 /* lo r */
          || graphicsChar == 191 /* up r */ || graphicsChar == 192 /* lo l */)

    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.

  4. 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:

    // For debugging
    /*
    

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.

digama0 commented 1 year ago
  1. 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 at mmfatl.c by @wlammen and mmtest.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.