I wanted to ask if there are any features (or add-ons) for Doxygen to measure the documentation coverage via command line. I already know that I can set up Doxygen to write undocumented elements as warnings into a log file, but to fully evaluate the documentation coverage from that, I'd need to write my own warning log parser. Was something like this done already or is there an even easier way I couldn't find? Is there any add-on I could check out for this?
Thank you.
I don't know anything that can give documentation coverage for doxygen, but a quick search gives 2 interesting results : https://github.com/alobbs/doxy-coverage (require xml output for doxygen) and http://jessevdk.github.io/cldoc/ (alternative for c++ projects?)
There is coverxygen which is using the same idea as alobbs/doxy-coverage (uses xml output of Doxygen) but provides more options (for example, filter by access specifier).
Disclaimer: I am contributing to that project.
Related
I am trying to print the dependencies associated with a code, such as definitions related to functions or variables in a statement using Emacs, however I am not finding the functions necessary to do it. I have already been able to parse the code, now I just need the printing part, for which I have been looking into the srecode package without success.
It will be a necessary step to translate Java code into C or C++
What "code"? In what programming language? There are packages for different programming languages that could help. You need to be more specific.
to use emacs at this point perharps was a bad idea. I searched for code slicing and found some tools here: slicers. For the translation part I may use code from cogre-srecode.el from the cogre package of cedet and for it the manual of srecode is better
The publish function in MATLAB works for both scripts and functions,
while the one for Octave works only for scripts: if I enter
publish myFunc.m
Octave gave
error: publish: Only Octave script files can be published.
Am I able to publish a function in Octave? If yes, how?
You can use Octave Forge generate_html package which is meant to generate html of individual functions. It is mostly used to generate the documentation of Octave Forge packages, and its defaults reflect that, but you could add any style you want.
This package will use the same help text that the help function in Octave sees which is the first block of comments in the file that does not start by Copyright or Author. You can have it in plain text but for nicer formatting, you can use Texinfo. In that case, the first line of the help text should be -*- texinfo -*-. There is a page on the Octave wiki with tips on how to write nice help text including a short section on Texinfo syntax (the actual Texinfo manual can be a bit overwhelming).
In addition to the help text, the generate_html package also identifies %!demo blocks and generates a section with the demo code and output it generates, including figures.
The best way to see how help text and demo blocks work in Octave is to check the source (as #Andy pointed out in the comments). For example, see the source for inpolygon (scroll to the bottom to find the %!demo blocks, right before %!test and %!error). The generate_html package generates this page (note the Demonstration blocks).
This is a "multiple questions in one" question, making lots of assumptions in between, so let's address those first:
1. I'll start by the question in the comment, since that's the easiest: Matlab's publisher is not a code documentation tool. It's a "make a quick report that includes both text and code to show at your supervisor meeting or write a quick point in a blog" tool. So the link you point to is simply irrelevant in this case, since that talks about documentation for matlab code.
2. The fact that matlab's publisher also "works for functions", particularly given the first point here, should be considered to be more of a bug than a feature, or at most as a trivial undocumented extension. If you look at the matlab documentation for the publish command, you'll see it expects a filename, not a function with arguments, and the documentation only talks about scripts and makes no mention of 'function' compatibility.
3. Furthermore, even if you did want to use publisher as a "documentation tool", this is counterintuitive for functions in this format, since you need to provide arguments in order for publisher to work (which will not be shown in the actual report), you'll need a modified version that displays intermediate calculations (as opposed to your normal version which presumably does not), and the function just spews an ugly ans= blabla at the end of the report. If your end goal is documentation, it might be best to write a bespoke script for this anyway, showing proper usage and examples, like matlab does in its actual documentation.
Having said all that, yes, there is a 'cheat' you can do to include a function's code in your published report, which is that, in octave (also matlab since R2016b), functions can be defined locally. A .m file that only contains function definitions is interpreted as a function file, but if there are other non-function-declaration instructions preceding the function definitions (other than comments), then it is seen as a script. So if you publish this script, you effectively get a published report with function code in it:
%% Adding function
% This function takes an input and adds 5 to it.
%% Example inputs
In = 10;
%% The function itself
% Marvel at its beauty!
function Out = myfun(In)
%% Here is where the addition takes place.
% It is a beautiful addition
Out = In + 5;
end
%% Example use
Out = myfun(In)
(If you're not happy about having to create a 'wrapper script' manually, you can always create your own wrapper function that does this automatically).
However, both the matlab and octave publishers are limited tools by design. Like I said earlier, it's more of a "quick report to show numbers and plots to your supervisor" tool, rather than a "make nice documentation or professional reports" tool. Instead, I would invest in a nice automated latex workflow, and have a look at code formatting tools for displaying code, and simply wrap that code in a script that produces output to a file that you can then import into latex. It may sound like more work, but it's a lot more flexible and robust in the long term, particularly since the formatting commands can be very quirky as well as limited.
Here is the (brief) context for my question :
I am working in VHDL (with Microsemi's Design Suite, Libero) and I use ModelSim to simulate my work. To that extent, I use a classic VDHL TestBench and, to save time, a .do Macro File.
This .do Macro file contains very basic commands such as "restart" or deleting/adding waves.
Even if I'm not expecting much from such a file, it would be convenient for me to include in it more actions, that I have to perform by hand with the Graphical Interface like, something that I use quite a lot : combining signals into a custom bus. This action is very simple to do in Modelsim's graphical interface but I can't find anywhere how to perform this in a .do Macro File.
So my question is :
Where can I find some good documentation regarding these ModelSim's .do Macro Files?
Or am I missing the point about the use of these files? Is it relevant to use it in sich a way?
I really hate to ask this kind of question here but, even if I was able to find some info here and there on various websites, I found nothing significant. I have been through quit a lot of ModelSim help documents or user guides but it almost always focused on the graphical interface.
You can find a command reference manual for your ModelSim version here:
www.microsemi.com/document-portal/doc_view/134097-modelsim-command-reference-manual-v10-3a.
You should also be able to find this and other documentation in ModelSim under "Help" > "PE Documentation - PDF Bookcase" (substitute 'PE' for the edition you are running).
You should see all the usual commands like 'add wave'. These can be used in .do files, and TCL script files.
You can use dividers to seperate signals with
add wave -divider -heigth 10 $DIVIDER_NAME
and also if you want to expand-collapse signals, you can add signal with
add wave -group $GROUP_NAME -position end ....
http://users.utcluj.ro/~baruch/resources/ModelSim/modelsim_user.pdf page 306
In some code coverage tools you can "hide" certain lines of code from the coverage tool, so that those lines do not count towards the coverage totals. For example, some code might be run only in circumstances that are hard or impossible to test (such as certain hardware failures). Thus, you might get 100% coverage reported even though some code was not exercised.
Setting aside for the moment whether this is wise, is this sort of thing possible with Perl's Devel::Cover?
(Devel::Cover can ignore entire files, but I am interested in ignoring just a few lines in a single file.)
A lot of uncoverable code features have been implemented but they are not documented because I wasn't sure of the interface. However, it's been a few years since anything changed in that area.
Probably the easiest way to see how to use the features is to look at tests/uncoverable in the distribution (see https://github.com/pjcj/Devel--Cover/blob/master/test/uncoverable). If you can't or don't want to change your code you can use the .uncoverable file (see https://github.com/pjcj/Devel--Cover/blob/master/tests/.uncoverable) and the cover options as mentioned by toolic.
If you do this, be sure to use the basic_html report which will mark a construct as in error if you tag it as uncoverable but it gets executed anyway.
I really should get around to tidying everything up and documenting it.
According to the TODO file on CPAN, this capability is not currently supported, but the developers see it as a valuable addition:
Enhancements:
Marking of unreachable code - commandline tool and gui.
The cover script mentions promising options: -add_uncoverable_point and -delete_uncoverable_point.
What's the best way to author man pages? Should I write using the standard man macros, or is there some clever package available now that takes some kind of XML-ified source and can output man pages, HTML, ASCII, and what not?
Thanks
I have previously used the GNU version of nroff called groff to write man pages.
Nice intro article on it here:
http://www.linuxjournal.com/article/1158
Doxygen is what you are looking for.
Keep in mind that it is designed to document source code but you could easily adapt it.
It can generate html, pdf, and latex documentation too.
If you are looking at writing once and generating different output formats such as manpages, HTML, plain txt, or even PDF, then docbook should work best.
A tool that is commonly used in the Tcl community is doctools which can produce a restricted (but useful) subset of the manpage format, suitable for rendering with groff or nroff. It can also generate both plain text and HTML directly.
For my atinout program I have been using ronn which lets you write man pages in a very, very readable markdown like syntax. I am extremely happy with it.
atinout(1) -- Send AT commands to modem, capturing the response
===============================================================
## SYNOPSIS
`atinout` <input_file>|`-` <modem_device> <output_file>|`-`<br>
`atinout` `--version`<br>
`atinout` `--usage`<br>
`atinout` `--help`<br>
## DESCRIPTION
**Atinout** reads a list of AT commands. It sends those commands one by one
to the modem, waiting for the final result code for the
currently running command before continuing with the next command in
the list. The output from the commands is saved.
...
see the whole page here.