OnlineCop / kq-fork

Fork of KQ r910. Just for fun.
GNU General Public License v2.0
15 stars 9 forks source link

Move comments from definitions to declarations (don't hate me!) #127

Closed OnlineCop closed 2 years ago

OnlineCop commented 2 years ago

This is not as intimidating as it first appears!

Steps:

  1. The first commit was a trivial clang-format cleanup for draw.cpp. Whitespace changes only.
  2. The second commit touches almost every source and header file but all it's doing is adding the parameter names to the declarations.
  3. The third commit was another clang-format kind of cleanup, where I moved the comments about the // pal[#] ==RGB{...} lines around so clang-format would stop mangling them. Essentially, whitespace changes only.
  4. ALL the rest of the commits, but you still should not hate me.

For Step 2, whenever there was a declaration where the parameter name was missing, such as void do_action(size_t);, I copied the parameter name from the implementation: void do_action(size_t fighter_index);.

Now comes to Step 4, the daunting one.

  1. To keep things straight, I modified one source and/or its one associated header file, in as close to alphabetical order as I could:
    • The first commit changed bounds.h and bounds.cpp only,
    • The next commit changed combat.h and `combat.cpp only,
    • etc.
  2. There were only a few exceptions to this:
    • Some of the fade.cpp declarations were in both fade.h and compat.h.
    • Some of the gfx.cpp declarations were in gfx.h and compat.h.
    • skills.h has a duplicate declaration (also found in hskills.h) whose definition is in hskill.cpp, so I added comments to both places.
    • unix.cpp and win.cpp have their common declarations in platform.h.
  3. Other than those, though, it was a 1:1.

For all the files modified in Step 4, it was modifications to comments ONLY.

This was why I updated the parameter names in Step 2 before I started this.

  1. The only changes you should see are comments moved, removed, or updated from .cpp files, and added or updated in the .h files.
  2. If you spot non-comment changes, let me know. I tried to be careful, but there were a lot of files to go through.
  3. Whenever there were inline static functions, the comments were moved like everything else.
    1. On a future pass, I'm hoping to get rid of as many static functions as possible, by wrapping whatever those files are doing into some kind of class/struct, where those static functions will simply be private: or protected: methods.
    2. Step 2 added a few missing static declarations so that the comment movement wouldn't introduce anything that wasn't strictly a change in comments.

And yes, I know that some of the changes were completely OCD (like adding punctuation and capitalization). The inconsistency was driving me up the wall. That just happened to be a bonus that happened while going through everything else.

Again, not as intimidating as it first appears!

pedro-w commented 2 years ago

Oof. Is this in addition to #116? We'd better clear the decks a bit before we start on this. (It's like one of those 10lb burger challenges where it's free if you can eat the whole lot in one go 😜 )

pedro-w commented 2 years ago

There were merge conflicts which I believe I have fixed. Please check!