Suppose you have a rather complicated README you want Doxygen to process to produce the mainpage of the documentation, something along the lines of
/*!
\mainpage Welcome to this code
\section S1 Introduction
Some stuff to explain why you coded all this
\section S2 Examples
Many examples of how the code can be used
!!! some line which you wouldn't write in a documentation
\section S3 Some other stuff
*/
AND you want doxygen to ignore the line beginning with !!! BUT you don't want to erase the line because you plan on editing it later.
Well, how can you do that?
EDIT: The following:
/*!
\mainpage Welcome to this code
\section S1 Introduction
Some stuff to explain why you coded all this
\section S2 Examples
Many examples of how the code can be used
\cond NEVER
!!! some line which you wouldn't write in a documentation
\endcond
\section S3 Some other stuff
*/
fails to put section S3 in the mainpage...
From the HTML commands section in the manual:
Finally, to put invisible comments inside comment blocks, HTML style comments can be used:
/*! <!-- This is a comment with a comment block --> Visible text */
The following:
/*!
\mainpage Welcome to this code
\section S1 Introduction
Some stuff to explain why you coded all this
\section S2 Examples
Many examples of how the code can be used
\internal
!!! some line which you wouldn't write in a documentation
\endinternal
\section S3 Some other stuff
*/
achieves the desired goal, provided your doxyfile is set correctly ( INTERNAL_DOCS tag set to NO ). I aknowledge #albert for the tip.
Related
Has anyone documented the differences between Stack Exchange Markup and Github Markup?
I'm in the midst of a project to convert Stack Exchange Markdown to Github Markdown. It might be a little more complicated because Jekyll on Github Pages uses a Markdown derivative called "Kramdown".
I've already written some of the conversion in my Python program. For example old SE posts with #Header must be converted to # Header.
Another example are "> Block quote" lines have two spaces appended to the end of the line.
Now it's starting to get tricky (for me at least) where in an image in SE is specified as:
[![Ubuntu 5 DE.png][1]][1]
**Note:** Blah, blah, blah
[1]: https://i.stack.imgur.com/MoxHd.jpg
It has to be converted to Github image markdown format:
**Note:** Blah, blah, blah
Another example of "footer hyper links" (for lack of a better noun) in Stack Exchange Markdown is:
- [Jack Master Volume?][1]
The simplest solution then is to install [JackMix][2]:
find listed [here][3].
[this script][4] is where you are heading:
[1]: https://discourse.ardour.org/t/jack-master-volume/84650
[2]: http://www.arnoldarts.de/jackmix/.
[3]: http://jackaudio.org/applications/
[4]: https://unix.stackexchange.com/questions/374085/lower-or-increase-pulseaudio-volume-on-all-outputs
Needs to be converted to Github Markdown format of:
- [Jack Master Volume?](https://discourse.ardour.org/t/jack-master-volume/84650)
The simplest solution then is to install [JackMix](http://www.arnoldarts.de/jackmix/.):
find listed [here](http://jackaudio.org/applications/).
[this script](https://unix.stackexchange.com/questions/374085/lower-or-increase-pulseaudio-volume-on-all-outputs) is where you are heading:
Finally tonight I discovered that in Stack Exchange you can have:
<!-- language: bash -->
#!/bin/bash
cat "$Filename.zip" | base64 > "$Filename64"
That needs reformatting to Github Markdown like this:
``` bash
#!/bin/bash
cat "$Filename.zip" | base64 > "$Filename64"
```
It gets even more complicated when SE Markdown has:
<!-- language-all: lang-bash -->
Or it has this:
<pre><code>Some lines of code
some more lines of
code </code></pre>
An existing Github Repo to convert would be awesome! If not then if someone has documented the differences between Stack Exchange Markup and Github Markup that would be great too.
If this question goes unanswered for a month then I guess I'll be answering it eventually after the trial-error-fix process is finished.
The self-answer seems to answer a different question, so I'll answer the one posed above.
Has anyone documented the differences between Stack Exchange Markup and Github Markup?
As of mid-2020, Stack Exchange uses CommonMark with support for a few custom features "like spoilers, MathJax, circuit diagrams, stack snippets, etc."
GitHub uses their own dialect, GitHub Flavored Markdown (GFM). The most notable extensions that GFM introduces are probably tables (supported on SE since late 2020), fenced code blocks (supported on SE since early 2019), and task lists (unsupported but also not really necessary on SE).
Most of the examples shown above work fine when rendered on Stack Exchange or by a compliant GFM implementation, but let's look at them in turn:
For example old SE posts with #Header must be converted to # Header.
This should have been cleaned up by the migration to CommonMark:
we will run a big migration across the network that will convert existing posts to use the new CommonMark format
Another example are "> Block quote" lines have two spaces appended to the end of the line.
Two spaces at the end of the line indicate a line break in Markdown, going all the way back to the original implementation.
Blockquotes do not require such line breaks, though they will rewrap without them. Line breaks and blockquotes are unrelated features.
Your image examples are interchangeable in both formats. Let's look at the SE one:
[![Ubuntu 5 DE.png][1]][1]
**Note:** Blah, blah, blah
[1]: https://i.stack.imgur.com/MoxHd.jpg
There is nothing specific to Stack Exchange here.
The [foo][1]… [1]: https://... syntax is a reference-style link which, again, comes from the original project. It is equivalent to the inline form [foo](https://...). Both forms work on both platforms. ![Ubuntu 5 DE.png][1]… [1]: https://i.stack.imgur.com/MoxHd.jpg is the same as .
On SE images are wrapped by a link by default, which introduces the wrapping [...][1]. But, again, this is not SE-specific. It's like comparing <img src="..."> to <img src="...">. This also works on both platforms.
Another example of "footer hyper links" (for lack of a better noun)
These are reference-style links already discussed and present in every version of Markdown I've ever seen, including the original project. They work in GFM as well as they do in CommonMark. No conversion is necessary.
Finally tonight I discovered that in Stack Exchange you can have:
<!-- language: bash -->
#!/bin/bash
cat "$Filename.zip" | base64 > "$Filename64"
That needs reformatting to Github Markdown like this:
``` bash
#!/bin/bash cat "$Filename.zip" | base64 > "$Filename64"
```
This is the only example above that requires any special behaviour at all. However, it mostly works out of the box. GFM supports indented code blocks and SE has supported fenced code blocks for over three years.
GFM doesn't understand legacy HTML-style SE language hints <!-- language: bash --> and <!-- language-all: ... -->, so it will render such code blocks without syntax highlighting. But they will still render as a code block.
The last example is just embedded HTML that both platforms (and the original) know how to render:
<pre><code>Some lines of code
some more lines of
code </code></pre>
With the exception of HTML-style language hints, every example you show above works out of the box on both Stack Exchange and GitHub Flavored Markdown. No conversion necessary.
Converting thousands of Stack Exchange Q&A in markdown format isn't as easy
as simply copying them over to GitHub Pages. The python program
stack-to-blog.py was used to convert Stack Exchange posts to
GitHub Pages Posts.
The full stack-to-blog.py program can be accessed on the
Pippim Website repo 🔗.
The program automatically:
Creates Jekyll front matter on posts and front matter totals for site.
Selects Stack Exchange Posts based on meeting minimum criteria such as up-votes or accepted answer status.
If self-answered question, the answer is included and not the question.
If self-answered question, the accepted answer alone doesn't qualify. Votes from other are the qualifier.
Initial testing allows selecting small set of random record numbers to convert.
Converts Stack Exchange Markdown formats to GitHub Pages Kramdown Markdown format.
Creates hyperlinks to original Answer in Stack Exchange and Kramdown in GitHub Pages.
Creates search word to URL indices excluding 50% of words like "a", "the", etc. to save space.
Selectively inserts Table of Contents based on minimum criteria settings.
Selectively inserts Section Navigation Buttons for: Top (Top of Page), ToS (Top of Section), ToC (Table of Contents) and Skip (Skip section).
Selectively inserts "Copy Code Block to System Clipboard" button based on lines of code.
Creates HTML with "Top Ten Answers" with the most votes.
Creates powerful nested expandable/collapsible detail/summary HTML for many thousands of tags by post.
Remaps hyperlinks in Stack Exchange Posts to {{ site.title }} website posts if they were converted.
Fixes old broken #header Stack Exchange Markdown.
Converts < block quote Stack Exchange Markdown into what works in Jekyll Kramdown.
Convert Stack Exchange <!-- language --> tags to fenced code block language.
When no fenced code block language is provided, uses shebang language first (if available).
Converts older four-space indented code blocks to fenced code blocks.
Converts Stack Exchange Hyperlinks where the website post title is implied and not explicit.
Prints list of self-answered questions that were not accepted after the mandatory two day wait period.
Prints list of Rouge Syntax Highlighting languages not supported in fenced code blocks.
Prints summary totals when finished.
Full documentation is provided here.
This is what program looks like when running:
I'm documenting my code using long sets of slashes to make them stand out in the code.
//////////////////////////////////////////////////////////////////////
/// #brief This is a simple test struct.
//////////////////////////////////////////////////////////////////////
struct Foo
{
//////////////////////////////////////////////////////////////////////
/// #brief Function with single line brief to demonstrate issue.
//////////////////////////////////////////////////////////////////////
void a() {}
};
I've built doxygen from a fresh subversion checkout and when it's run on the code above the line of slashes at the end of each block are included in the brief description. The problem doesn't exist in doxygen 1.8.1 that's installed on my system, so this appears to be a bug in the doxygen trunk.
I've submitted bug 700345 to the doxygen project, but am interested in taking a shot at fixing this myself.
I'm having trouble finding the code doxygen uses to detect the end of comment blocks. Does anyone have experience working with this part of the code and have a moment to point me in the right direction?
FYI, a quick solution to this is to add a blank comment line after the #brief. I'm not interested in going through ~100k lines of code to identify problematic comment blocks and add a blank line (yet).
See my proposed fix attached to the bug report you submitted.
In Org-mode you can make comments and from Org-mode you can export to LaTeX but Org-mode comments are not exported to LaTeX comments. How can Org-mode be made to export Org-mode comments as LaTeX comments?
Here is an example. The following
* Test
Text before comment
# Comment
Text after comment
Text before comment
#+BEGIN_COMMENT
Comment
#+END_COMMENT
Text after comment
exports to
\section{Test}
\label{sec-1}
Text before comment
Text after comment
Text before comment
Text after comment
But I want the Org-mode comments to be exported as LaTeX comments. Thus, I want the following LaTeX output:
\section{Test}
\label{sec-1}
Text before comment
% Comment
Text after comment
Text before comment
\begin{comment}
Comment
\end{comment}
Text after comment
I am running Org-mode 7.6 in Emacs 23.3.1.
Under the current exporter the only method I can think of that would allow you to export comments would be backend-specific. You could use something along the lines of:
#+latex: comment
or
#+begin_latex
\begin{comment}
comment
\end{comment}
#+end_latex
However both are contrived and you would need to do the equivalent for HTML etc if you intend to export to more than one format.
There is a new exporter in development however where this should not be overly difficult to implement (comments are already identified as blocks in the parser so it would simply need a method to convert them on export).
I'm forwarding this request to the mailing list to see if this can be included.
Edit: Thread located here.
Edit: Response from the maintainer of Org-Mode
the current exporters don't allow this, but the new export engine by
Nicolas makes it possible.
The plan is to merge the new export engine into Org's core before
version 8.0, so please stay tuned.
In addition to Jonathan Leech-Pepin's answer, there is a hackish way of doing it for a given exporter backend. Comments are handled in the org-export-handle-comments function, which is called by org-export-preprocess-string in org-exp.el. Each exporter backend is different, but let us consider the LaTeX backend.
If you look in the org-export-as-latex function in org-latex.el, you can find calls to org-export-preprocess-string. One of the things passed to the org-export-preprocess-string function is a parameter list, in particular it contains a :comments parameter, which in the LaTeX case is set to nil. This parameter tells the org-mode exporter what to do with comments - for the details look at the call to and implementation of org-export-handle-comments in org-exp.el. Essentially, the :comments parameter can be a format string showing how to handle the comments; if it is nil, this means no format handling so nothing is printed. If, in the org-export-as-latex function, you replace :comments nil with :comments "%% %s", then this will insert a "%" in front of whatever the comment text is upon export. So in your case
this is text before a comment
# this is a comment
this is text after a comment
would be exported as
this is text before a comment
% this is a comment
this is text after a comment
This isn't the most convenient way of doing things, and I'm not sure of a way to specify the :comments parameter on a per-file basis. Maybe something in the thread Jonathan set up will shed some light on this subject.
Note that you may need to remove the byte-compiled org-latex.elc file in order to see your changes in org-latex.el propagate through to the export.
I've just installed and setup an instance of Doxygen, but out of the box it only finds TODO tags in code when marked in a block like:
/**
* #todo Foo
*/
It doesn't seem to find:
// TODO Foo
// FIXME Bar
// #todo Baz
Most IDE's and bug trackers which handle parsing are fine with them, is there an easy way to configure Doxygen to find them and list them as ToDo items?
There are a number of examples and methods we can use:
For a one line comment with valid doxygen commands (e.g. \todo) you would use
/// \todo Some (optional) text
Note the three forward slashes, not the usual two. See point three on the second list in the special documentation blocks section of the doxygen documentation. This can be used to add new todo items to your source code.
Generally one can define custom tags (like FIXME) by defining an alias in the Doxygen configuration file. For example
ALIASES += FIXME="\todo"
which will allow you to write \FIXME in your source code and the comments prefixed with \FIXME will be included in you todo list in the final documentation. The problem here is that you have to prefix your aliases with the \ (or #) symbol and begin the comment with three leading forward slashes which, if you want to leave the FIXMEs in your code as they are, is not an option.
Finally, an alternative method, and what I think you are looking for, would be to preprocess your source files using the INPUT_FILTER configuration file option. This option defines a command that is applied to each of your source files before doxygen builds the documentation, so we can define a command which replaces instances of TODO and FIXME with valid doxygen markup.
INPUT_FILTER = "sed -e 's/\/\/.*FIXME/\/\/\/ \\todo/'"
This filter replaces all instances of // FIXME (with any amount (or none) of whitespace between // and FIXME) with /// \todo. This substitution is made internally by doxygen only: your source files are not modified on disk.
Note: This last point was inspired by the accepted answer to the question Getting doxygen and MSVC TODO tags to work together. However, that answer used the FILE_VERSION_FILTER configuration option rather than INPUT_FILTER. I think that the latter (INPUT_FILTER) is actually more appropriate here. Also, the sed command used in that answer does not work for me.
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.