search

aseba-community / aseba

Aseba is a set of tools which allow beginners to program robots easily and efficiently. To contact us, please open an issue.
http://aseba.wikidot.com
GNU Lesser General Public License v3.0
49 stars 61 forks source link

Move doxygen comments of public declarations from cpp to header files #846

Open ypiguet-epfl opened 6 years ago

ypiguet-epfl commented 6 years ago

At some places such as in aseba/compiler/compiler.cpp for method compile, the doxygen documentation of public methods is located in the cpp file. It would be better to put it in the header file (aseba/compiler/compiler.h), because the cpp file could be provided as compiled code and not readily available. That's already the case for some of the public declarations (e.g. struct SubroutineDescriptor).

cor3ntin commented 6 years ago

Would you be willing to make a PR ?

ypiguet-epfl commented 6 years ago

I think the git/github work wouldn't be worth the trouble for someone like me whose PR are limited to minor code polish. This can wait.

stephanemagnenat commented 6 years ago

For information, this was a design choice: at the time the compiler was written, code folding wasn't very widely available in editors and so the idea was that either someone knows more or less the code and wants to get a quick look at the available functions, and thus reads the h file, or this person wants the detailed information, and reads the generated documentation. This rationale might still be valid for people using editors such as vim.