Is there a simple way to count how many functions, methods and/or classes there are in a library? And how many are documented? Maybe through Doxygen output?
When I try to Google a solution all I get is algorithms to count things... :)
There is a tool named Coverxygen which requires XML output from Doxygen.
Install it by:
pip install coverxygen
Bonus:
If you use Sphinx and Doxygen (and Breathe) to generate documentations, you can use DocsCov to make a badge showing documentation coverage to show on your README.
As Xin Huang pointed out in a comment above, there is a useful tool called doxy-coverage.py at https://github.com/alobbs/doxy-coverage. It prints, for each file documented with Doxygen, it prints how many entities it has (namespaces, free functions, classes, member functions, enums, #defines, etc) and how many of those are documented. It lists each of the non-documented entities. At the bottom it gives a summary of the documentation coverage (percent entities that are documented). It uses the XML output of Doxygen to do so.
I replaced the line
print("%d%% API documentation coverage" %(total_per))
by
print ('%3d%% API documentation coverage (%d of %d)'%(total_per, total_yes, total_all))
To add the total number of entities and total number of documented entities in the project.
It seems possible to modify the tool to distinguish entities by type. If I ever do this, I'll post the resulting code here.
Related
I am currently documenting a F95/2003 software project with the help of doxygen. On the one hand I grouped corresponding pages with the help of #defgroup, #addtogroup, #ingroup.... which end up under the point Modules in the table of contents and the top menu. Then the project also contains Fortran Modules, properly documented, and they appear also as a separate Modules point in the table of contents, which makes them hard to distinguish. How can I rename one of them? Like naming the Module pages generated from the Fortran modules' documentation as Fortran Modules or the best option would be to get completely rid of the separate Modules pages for the Fortran modules, since they also belong to a doxygen group and can be found there asl well?
In principle the "Fortran modules" are listed as namespaces, but by means of the OPTIMIZE_FOR_FORTRAN = YES the name is changed into "Modules". To get the correct naming is of course a difficult problem.
Doxygen has also the possibility to change, in respect to names and showing / hiding) some layout elements, see the doxygen manual paragraph: "Changing the layout of pages" (http://doxygen.nl/manual/customize.html#layout).
when creating a layout file say:
doxygen -l mylayout.xml
and changing here the line (approximately line 8):
<tab type="namespaces" visible="yes" title="">
into
<tab type="namespaces" visible="yes" title="Fortran Modules">
and setting in the doxygen configuration file (Doxyfile):
LAYOUT_FILE = mylayout.xml
I think you get the effect you want to have.
The following I didn't try (so I don't know what the effect might be in your case, and I have big doubts but I mentioned it here for completeness as it came into my mind), but doxygen has also the \namespace command maybe you can use this in this case in stead of the grouping commands.
I am using doxygen to document my code. I found I can easily find all the classes since there is a tab calles "classes". But I cannot get all the free functions listed together. I have to go to the tab "files" to look for them. Can I put all free functions together in doxygen documentation?
There is a method to group items in pages and the method involve some comment writing from your side. There is not yet available an automated way to group free functions together.
Still using the grouping option, you can place all items you want into a given page in documentation. More about this and some examples at the Doxygen page:
Doxygen/manual/grouping
I'm working on a C++ project and really fell in love with the Sphinx documentation build system. I managed to setup Doxygen and Breathe to produce and provide the C++ descriptions to Sphinx.
I can't figure out how Google's Ceres Solver documentation was done. Their API reference for example contains class names followed by lots of text, sometimes even with code block examples as shown in the previous link. Is there a way to write Doxygen documentation inside the source files and achieve this?
Another example is this class documentation, which has around two pages of text. I somehow doubt that all this text is located in the source files as Doxygen comments. I have the feeling that all the extra text has been written in the restructured text sources for the documentation and nothing in the c++ source files. But then what is the point of using doxygen and breathe...
Or asked differently, where should I put high-level information about the code? I mean I can document class1 and class2 in their sources, but somewhere I need to explain how both of them interact and are used together. This is what the documentation of the Ceres Solver does so nicely in my opinion.
Alternatively you could point me to a C++ project with the Sphinx + Doxygen + Breathe pipeline and open source documentation. Then I can see for myself how to do these things. Unfortunately I don't know about any project.
I missed the github link for the Ceres Solver. There the sources of the documentation can be found. I'm a bit disappointed, because the complete documentation is written in the Restructured Text source files and NOT inside the c++ code. Basically they reference the class name with .. class:: className and then add ReST markdown for informative text, example code blocks etc. One example is given in "Modeling Non-linear Least Squares"
I work on unix.
I have my complete source code in unix in the form of building blocks and modules.
Like headers,sources files,make files etc.
I can copy all the files with the same directory structure to windows.
I need some tool which will convert all the source to html tags with all the links to functions,variables,classes,headers.There should be some tool to do this easily.
by this way it would be easy for debugging the code in a fast way.
Is anybody aware of such tool?
The term you're probably looking for is "documentation generator". You're specifically interested in ones that output HTML files.
Doxygen is popular, but if you want a master comparison list of documentation generators Wikipedia has a summary:
http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
Looking at the output generated by the different programs (on projects that use them) will probably inform your choice of which meets your needs.
You can use doxygen to generate your documentation. In its basic form it will generate what you need but to add comments that appear in the final html you will need to use special style comments.
What means this special comments in qt examples folder?
I know about "//:" this is a comment than would be taken to a translation program if the next line contains tr("").
The code between //[] seems to be taken to the generated html documentation.
Is there a document with full description of special comments?
Qt uses Doxygen Special Commands in it's code comments. [Okay, to be correct, Doxygen extends Qt's comment special commands.] The special commands are used to control the generation of the documentation when it is run on the code. The Trolls who maintain Qt have their own tool they use to generate documents from the code. Doxygen was written to give us mere mortals a tool we could use.
One of the things you can do with Doxygen (and I assume Qt's tool) is include example code in the documentation. Often, only part of the code is needed, so there are some special commands that can be used to control what portion of the file is displayed (e.g. \line). They rely on finding markers in the code. IMHO, the // [xx] are simply those markers.
This is the document for translation comments, no mention of //[num] though....