I would like to hear what positive or negative reviews people can give for source file "automatic" documentation generators. What program do you recommend that I give a try. I see that there is FORD, Doxygen, Sphinx-Fortran, ROBODoc, Fortrandoc and others. Your suggestions are appreciated. Thank you.
I have personally found FORD to be adequate, for the challenge often is not automatic generation, rather the authoring of good content itself that often gets overlooked amid all the focus on the mechanics.
Nonetheless, I will strongly suggest you ask this question on the Fortran Discourse here: https://fortran-lang.discourse.group/ that can help you gain broader feedback from the Fortran community.
Modern (aka auto-generated) documentation sucks. At least that is in my opinion. In many cases, it now requires you to have multiple copies of the documentation open in different places to make sense (unless you have an eidetic memory).
I work with Doxygen, which I found in most cases a good choice for Fortran. Unfortunately, there is no support for submodules currently as far as I know.
I shortly tested FORD and I think it's the best suited auto-documentation tool currently. However, I found no time to change the already existing Doxygen headers/tags in my many source files. For new code definitely a good choice.
Sphinx I use for Python but not Fortran. For Python I find it personally compared to Doxygen much more time consuming to get the same results - a lot of extra work is needed and you still need some extra modules. Maybe I'd not spent enough time in reading the documentation... But it's clearly no quick solution. I have no idea whether the Fortran extension is better in this regard. As Doxygen Sphinx has not been developed directly for Fortran.
I have used RoboDoc for many years.
It is open source, and works well, but I gather that the original developer is no longer actively supporting it.
As in FortranFan's reply, the key is in discipline and good commenting of the code. If you have discipline, always comment new code when you add it, and when you modify it, then it is possible to end up with some good documentation.
If you're a single developer, then it is easy - no one to blame but yourself if the documentation is not up to date. In a team, then as long as everyone plays ball, you should be able to make it work.