At Sat, 19 Jan 2019 19:39:08 +0100 Hans <hguij...@xs4all.nl> wrote: > > On 19/01/2019 19:29, Robert Heller wrote: > > I'm presuming these classes are not actually in a public API library -- > > either > > they are defined in "private" header files (header files only ever included > > in > > the corresponding to the C++ main for the exe in question) or defined > > directly > > in the C++ files specific to the exe in question). It might also make sense > > to > > NOT use "correct" Doxygen commentting -- include comments of course, but not > > formatted in a way that Doxygen recognizes (eg replace /** with /*+, etc.) > > -- > > Doxygen won't pick them up and won't document them (and won't get confused > > or > > create confusing documentation). Since they don't document a public API, > > there > > is no harm. Or don't actually feed the "private" header files or C++ source > > code to Doxygen (unless you are using the C++ main program to create man1 or > > man8 pages, or something like that -- eg program usage docs). > > > > As Richard says "That isn't really how Doxygen is intended to be used...", > > you > > probably *don't* want to "document" a non-public API, which is what these > > classes sound like what they are. Doxygen is meant to document *public* APIs > > (programs, classes, functions, etc.) that will be called by programs written > > by other people, who would then link with your library or run your main > > programs (your .exe files). > > Well, an executable doesn't have a public API of course, it's a closed > unit so it's all private. My goal here is overal project documentation. > It is for new developers, allowing them to better understand the system. > > Is that actually an unusual use for Doxygen? It seems perfect for doing > something like this - well, apart from the issue under discussion...
Normally, I use Doxygen three ways (and guess this would be typical): 1: Document a public library's API (classic use of Doxygen). Create documentation for programmers who might be interested using the libraries in their own programs from the comments in the source code. 2: Create man1/man8 pages for utility and daemon programs (document things like command line arguments, files used, etc. This helps end users to properly run these utility and daemon programs that are part of the project. 3: Write out-of-program user manuals (the source header files will contain only Doxygen-style comments and no actual code) -- Doxygen is good here in that it creates quality "hard copy" (printable PDF) by way of LaTeX AND equally quality "help pages" (as HTML), from a common source. The two formats are consistent with each other and cover both use cases -- eg those that like to click on a Help button or menu and have the documentation on the screen alongside the running program and those that want a paper manual to read. (In practice, 1 yields man3, PDF, and HTML, 2 yields man1/man8, and 3 yields HTML and PDF, and when creating a user manual for a complex project, the user manual uses sources for both 2 & 3 -- eg, the "man" pages for the utility and daemon programs end up in their own chapters or in the appendix. Feel free to visit my Model RR System's source tree on GitHub at https://github.com/RobertPHeller/ModelRRSystem for a package where I do this.) For what you are doing you either need to run Doxygen for each "program" separately, creating a separate self-contained document OR you need to put the "private" classes in program-specific name spaces. *Actually* there are all sorts of good reasons to do that anyway. When the classes, etc. are in program-specific name spaces Doxygen will properly consider them different and distinct from each other. > > > > > > > _______________________________________________ > Doxygen-users mailing list > Doxygen-users@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > > -- Robert Heller -- 978-544-6933 Deepwoods Software -- Custom Software Services http://www.deepsoft.com/ -- Linux Administration Services hel...@deepsoft.com -- Webhosting Services _______________________________________________ Doxygen-users mailing list Doxygen-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/doxygen-users
