I think the main barrier to good documentation is the amount of reverse engineer it would require at this point.
I've never found Doxygen to be so helpful but also have not used it much. Unlike other languages such as Java, C++ is designed to allow separating interface from implementation, so better to just use this to being with. Sphinx seems unnecessarily cryptic to me but serviceable. On Thu, May 2, 2019 at 10:22 AM Alan Carroll < solidwallofc...@verizonmedia.com> wrote: > Yes, although doxylink requires a couple of patches to work well with > C++17. I have PRs up on the repo for those fixes, but need to find time to > write some unit tests to get them accepted. > > The goal is to have Doxygen generate reference material, while Sphinx > provides higher level descriptions of the API. Not to mention that when a > developer goes looking for information, the function/class/method > definition is usually the first place he checks, and having Doxygen based > reference information there is a big help. > > But who am I to dispute the ATS tradition of undocumented and inscrutable > API? Nobody else seems to care. > > On Thu, May 2, 2019 at 9:25 AM Walt Karas <wka...@verizonmedia.com.invalid> > wrote: > >> Alan do you mean this? https://pythonhosted.org/sphinxcontrib-doxylink/ >> >> On Thu, May 2, 2019 at 9:21 AM Leif Hedstrom <zw...@apache.org> wrote: >> >> > >> > >> > > On May 2, 2019, at 08:17, Alan Carroll >> > <solidwallofc...@verizonmedia.com.invalid> wrote: >> > > >> > > Yes they can work together. I presented on that at the Summit, you >> should >> > > have been there. >> > >> > I should have. >> > >> > So is that setup today? Where does it go? How does it synergize with all >> > existing API docs? >> > >> > And, stop inlining Doxygen comments in function prototypes!!! :-) >> > >> > — Leif >> > >> > >> > > >> > >> On Thu, May 2, 2019 at 9:15 AM Leif Hedstrom <zw...@apache.org> >> wrote: >> > >> >> > >> +1 on docs. >> > >> >> > >> However , I think it’s a bit of a mess now with Doxygen sometimes, >> and >> > >> normal Sphinx docs (most of the time?). It seems we should have one >> way >> > of >> > >> documenting our interfaces and APIs, no? I find often times, Doxygen >> can >> > >> get in the way of code formatting / indentation, specially when >> > inlined. I >> > >> really dislike that. >> > >> >> > >> It’s probably time to decide. If we decide to go Full R on Doxygen, >> > >> someone has to shepherd that and start working on it. If not, I >> think we >> > >> should drop all Doxygen in favor of just Sphinx. Unless Sphinx and >> > Doxygen >> > >> work together in some way that is above my pay grade ? >> > >> >> > >> — Leif >> > >> >> > >> Found this: https://breathe.readthedocs.io/en/latest/ >> > >> >> > >>> On May 2, 2019, at 06:19, Alan Carroll >> > >> <solidwallofc...@verizonmedia.com.invalid> wrote: >> > >>> >> > >>> They shouldn't become invalid during the callback invocation, but >> may >> > >> after >> > >>> the callback returns. >> > >>> >> > >>> As for Doxygen, perhaps I am simply weird in that I like to have >> > >>> documentation for API that I call. I guess I'm just not smart >> enough to >> > >>> deduce the meaning and function from only the function and parameter >> > >> names. >> > >> >> > >> > >> >
