I'm not sure about Javadoc, but with Doxygen you do not need to put inline documentation immediately next to the code you are documenting. You could put all the

I'm not sure about Javadoc, but with Doxygen you do not need to put inline documentation immediately next to the code you are documenting. You could put all the documentation at the top of the file and the function declarations at the bottom. This makes it a little harder to maintain the docs while you maintain the code, but it does resolve one of your pain points.