search

hannorein / rebound

💫 An open-source multi-purpose N-body code.
https://rebound.readthedocs.io/
GNU General Public License v3.0
820 stars 217 forks source link

clang-docify a few things in rebound.h #708

Closed spenczar closed 11 months ago

spenczar commented 12 months ago

As we discussed a bit in #705, clang-doc style documentation comments brings some benefits for automated tools, like generating bindings. This is a little mini-PR of a bit of what the changes might feel like. I tried to cover a bunch of the scenarios we'd encounter if we converted everything.

If I'm honest, I don't think these seem like improvements for the C code. Enums get way bigger to document every value. Inline function comments need to be put in front, which kind of chops things up and makes symmetries less obvious. The only clear success case is probably commit 5df64af, which I think certainly makes things a little more readable.

hannorein commented 12 months ago

I agree with everything you wrote. I'm not very enthusiastic about the changes except maybe a few like the 5df64af you point out. In most cases they make the code less readable - but I'm also obviously biased because I know it from before. If you were to push for it I think you could convince me to go ahead. But if you're not, then I'd say we don't do it? It might just not be worth it.

spenczar commented 11 months ago

I agree, this doesn't seem worth it. Let's drop it - I'll add notes to the bindings directing any users to look up documentation by looking at rebound.h.