Fix Doxygen warnings

[birm]

Resolution of Doxygen Warnings, Mostly wrong/missing/extra params, section renaming and latex/doxygen commands. Things that may require additional attention are flagged with comments.

[birm]

I don't know why this fixed this, or why it was an issue. Not a latex person.

[zoq]

If I remember right \f{ wil not center the formula, really strange that we get a warning here.

[rcurtin]

@birm you are my hero! This has needed to happen for way too long and I'm really appreciative that you just went and did it. I left some comments throughout (all of them should be easy I think!).

I noticed that in many places you added directories to the @file annotations. Do we want to add a 'general rule' about that? Where, e.g., all of the @file annotations start from under src/? e.g. @file mlpack/core.hpp or @file mlpack/bindings/cli/param.hpp, etc. Maybe that could be more consistent. Let me know what you think. 👍

[birm]

Thanks both @zoq and @rcurtin for looking over this giant PR!
Regarding the \file paths, I just used the minimum unique one. It's probably reasonable to ask contributors to make this change to both new and old files as required, but maybe it's better to keep it consistent. I'm not sure, so open to thoughts on that.

[rcurtin]

Regarding the \file paths, I just used the minimum unique one. It's probably reasonable to ask contributors to make this change to both new and old files as required, but maybe it's better to keep it consistent. I'm not sure, so open to thoughts on that.

I thought it would be super tedious to use a full path, but, then I realized it's really easy to write a script to do it:

for i in `find ./ -iname '*.[hc]pp' -printf '%P\n'`; do sed -i 's|^ \* @file.*$| \* @file '$i'|' $i; done

(It could probably be done entirely with find, but, whatever.)

You can run that from src/ if you want the @files to be like @file mlpack/bindings/cli/end_program.hpp, or run from src/mlpack/ if you want the @files to be like @file bindings/cli/end_program.hpp. I don't think I have an opinion on which of those is better.

[birm]

the idea of having the full paths in \file looks good to me now that it's done. On a quick look, I didn't notice any cases where this made the line too long.

[zoq]

Let me rerun the failed ci jobs.

[zoq]

For some reason the job keeps failing, but not only for this PR.

[rcurtin]

Files changed: 1,207 😮

Anyway, looks good to me. I'm not bothered by the randomly failing build (it doesn't seem related to this PR, at least). Thank you for putting in the time to get this all worked out! 👍

[birm]

Let me pull in upstream changes... Now it's a 1209, which is cool because 1209 divides 92^2 - 1 (I was hoping for a more interesting fact about 1209 from wolfram...)

[rcurtin]

I tried Wikipedia; 1209 turns out to be the year Cambridge University was founded.

[zoq]

Wow, this is just great, no further from my side, thanks!

[birm]

Any requests for commit cleanup? (Should I leave it be, squash some commits, squash all)