I am documenting my code with doxygen and want to introduce a separating line after a short description. What command can I use to include a separator? I have seen a series of separating lines in the doxygen manual but cannot find the appropriate command.
As noted in albert's comment, the syntax is <hr>.
Note that this does not work equally well in all output formats, but it does work in HTML. See albert's comment below.
Related
We use DocFx in our projects. We would like to check for no problems in VSCode but we get the warning link.no-such-reference for DocFx Note formatting which uses square brackets.
Do you support suppression of problems like using:
[//]: # (<!-- markdownlint-disable line-length -->)
Could not find any documentation about suppressing one problem type once at a single code line.
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.
Many man pages and --help option use a format for describing the command line options of the documented utilities. For instance, for the cd shell command:
cd [-L | -P] [directory]
cd -
I'd like to parse these descriptions. Is there a model or formal format (even if it is not widely accepted)?
I've seen that at least python's argparse (http://pymotw.com/2/argparse/) can generate something like that.
Some details about the notation used for the SYNOPSIS section can be found in the man manual:
The following conventions apply to the SYNOPSIS section and can be used as a guide in
other sections.
bold text type exactly as shown.
italic text replace with appropriate argument.
[-abc] any or all arguments within [ ] are optional.
-a|-b options delimited by | cannot be used together.
argument ... argument is repeatable.
[expression] ... entire expression within [ ] is repeatable.
Exact rendering may vary depending on the output device. For instance, man will
usually not be able to render italics when running in a terminal, and will typically
use underlined or coloured text instead.
The command or function illustration is a pattern that should match all possible
invocations. In some cases it is advisable to illustrate several exclusive
invocations as is shown in the SYNOPSIS section of this manual page.
There are further details in the the POSIX Utility Syntax Guidelines.
Many libraries to parse the command line options can generate the synopsis section (e.g. take a look at boost::program_options).
I'm looking for a way to generate and insert header comment blocks above my functions in Emacs (in any mode), with the default contents of the comment automatically based on the function's signature (i.e. the correct number of #param place-holders).
Doxymacs is a nice candidate. But I prefer another way works without the necessary libs. Can anyone recommend some others ways for adding smart comments for functions in Emacs? Thanks.
Edit:
Now I found this: http://nschum.de/src/emacs/doc-mode/, but it seems that it does not work well after I require it into my .emacs and add hook for js-mode. Doesn't it support js functions ?
I don't know of any general-purpose approach.
Csharp-mode has a defun that is bound to / , which tries to generate comments appropriate for C#. The way it works: Every time you type a slash, it looks to see if it is the third slash in a row. (In C#, three slashes are used to denote comments that produce documentation). If it is the third slash, then it looks at the surrounding text and inserts a comment skeleton or fragment that is appropriate.
It is not generalized in any way to support javascript or other language syntaxes. But you might be able to build what you want, if you start with that.
here's the excerpt:
http://pastebin.com/ATCustgi
I've used doxymacs in the past and I've found it useful
http://doxymacs.sourceforge.net/
I know different methods of introducing multi-line comments in Perl. But I want to know why it doesn't have something simpler multi-line comment feature such /* comment */, which would make it much easier.
I currently follow http://www.perlmonks.org/?node_id=560985 to achieve multi-line comments. Are there any plans to include this feature in Perl anytime soon?
C-style comments come with a variety of difficult problems, including the inability to comment-out comments. Additionally, convenient syntax for one-line encourages concise writing, which makes your code easier to read. The absence of 10-line "Author: ... Input: ... Output: ... Favorite Color: ..." blocks that you see from time to time in C and C++ is another benefit.
Multi-line comments encourage long writing that is better expressed more concisely or as documentation, so this is what Perl encourages with its # and =pod operators (respectively).
Finally, if you are having trouble with Perl's style of commenting, you should configure your editor to edit programs, not text. In Emacs, if you start writing something like # this is a comment that is getting longer and longer and longer and oh my goodness we are out of space on this line what to do now and type M-q, Emacs will automatically insert the # at the beginning of each line that it creates.
If you just want to comment-out a block of code, then you need look no further than M-x comment-region and M-x uncomment-region, which will comment out the region in pretty-much any language; including Perl.
Don't stress about the syntax of comments; that's the computer's job!
There was a discussion regarding this on the perl6-language#perl.org mailing list. Although in the end the discussion was inconclusive, the summary posted here makes for interesting reading.
As with any multiline comment structure, there will be a "open" and a "close" comment condition, and that leads to problems with nested comments.
for example, C uses /* as the open and */ as the close. How does a multiline comment system handle comments within comments? C will fail if you try to comment a block that is already commented.
Note that line-based comments (e.g. c++ // comments) do not suffer this problem.
Simplicity is in the eye of the beholder. That said, there are already a number of ways to do multi-line comments. First, void string literals:
q{This text won't do anything.
Neither will this.};
This has the unfortunate side effect of triggering a warning:
Useless use of a constant in void context at - line 4.
Another option is using a heredoc in void context - for some reason this doesn't cause a warning:
<<ENDCOMMENT;
Foo comment bar.
ENDCOMMENT
As you can see, the problem isn't the lack of syntax as such (python doc comments look vaugely similar to the q{} method in fact) - it's more just that the community of perl programmers has settled on line comments using # and POD. Using a different method at this point will just confuse people who have to read your code later.