I would like to know whether it is possible to define own doxygen comment styles. The usual style is something like this (Javadoc-like):
/**
*
* Descriptions and stuff
*
*/
or (when using Qt):
/*!
*
* Descriptions and stuff
*
*/
I would prefer something like
/*!===============================================================
*
* Descriptions and stuff
*
================================================================*/
But the doxygen parser doesn't allow this syntax. So my questions is, if there is a way to define own comment styles.
I don't think you can define your own comment styles, but with some slight changes to the format, it might match.
See this page on documentation blocks in the Doxygen documentation:
Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following:
/********************************************//**
* ... text
***********************************************/
(note the 2 slashes to end the normal comment block and start a special comment block).
or
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
Related
In building my documentation I'm running into a lot of warning messages such as the following:
/home/X/Y/src/core/include/math/bigintntl/transformntl.h:92: warning: documented empty return type of NTL::NumberTheoreticTransformNtl::ForwardTransformToBitReverseInPlace. I'd like to turn off the specific warnings related to X is not documented. How might I go about doing so? I'm building the documentation of a rather large library, and until we have time to go back and update the docs, this just adds a lot of noise to our builds.
The documenting line:
/**
* In-place forward transform in the ring Z_q[X]/(X^n+1) with prime q and
* power-of-two n s.t. 2n|q-1. Bit reversing indexes. [Algorithm 1 in
* https://eprint.iacr.org/2016/504.pdf]
*
* #param &rootOfUnityTable is the table with the n-th root of unity powers in
* bit reverse order.
* #param &element[in,out] is the input/output of the transform of type VecType and length n.
* #return none
*/
void ForwardTransformToBitReverseInPlace(
const VecType& rootOfUnityTable, VecType* element);
from OpenFHE library
and the .rst file looks like the following (autodoxygenindex is a Breathe directive: https://breathe.readthedocs.io/en/latest/directives.html#autodoxygenindex):
Core Math Big Int NTL Documentation
=========================================
.. autodoxygenindex::
:project: core_math_bigintntl
while the conf.py file is here.
Looks like the issue for me was that breathe was regenerating the documentation because I was using a specific command. Unfortunately, this regeneration seemed to ignore the Doxyfile that was coming in. So, I had to manually pass in the relevant variables via breathe_doxygen_config_options See breathe config-values
Basically I want to write one piece of text which qualifies both as a working code and MarkDown (preferably GitHub flavor) for documentation. The language I'm using has C form commenting \\ for rest-of-line and /* ... */ for multi line comments. So far what I can do is:
/* --> start with multi line comments
here some markdown text
# heading
* list
end markdown section with
<!--- */ // -->
or
[//]: # (end of comment block --> */ // <-- inline comment)
_-_-indented code
_-_-_-_-more indented code
The issues are:
the first /* still showing in the documentation
I can't use the proper multiline code block ``` ... ```. I have to indent the code parts once more than what is required. Also the syntax highlighting doen't work in this format AFIK.
I would appreciate if you could help me know first how to solve above issues. and Secondly if there is any better way to do this?
I think I have a proper solution now with colapsible / foldable code section:
/*
This is the markdown **text**
used for documentation
<details>
<summary>Click to see the source code</summary>
``` scilab
*/
This is the
actual code
which will
be executed
/*
```
</details>
<!--- */ // -->
which will be rendered as:
/*
This is the markdown text
used for documentation
*/
This is the
actual code
which will
be executed
/*
The collapsible section makes sure that the documentation is clean and readable. you may see the final result here on GitHub. I used the code from here. Now there are a bunch of /*s and */s which would be nice to get ride of. Next step would be to modularize the MarkDown document into different files as I have asked here.
P.S. Implementation of the same idea using AsciiDoc here.
Is there a way to comment M code / comment out lines or blocks of code?
M supports two different types of comments:
Single line comments can be started with //
You can comment out multiple lines or comment out text in the middle of a line using /* */ (e.g. = 1 + /* some comment */ 2)
Comments might seem to disappear in the formula bar if they are at the end of the line, but they are still there. You can verify this by looking at your code in the Advanced Editor.
I want to have comments work in the traditional way they do In C in Apple's Xcode. I have installed VVDocumentor and I really like how the default way it comments is, i.e.:
/*
* Comments go here
*/
/*
* multiple
* lined
* comment
*/
I hoped to be able to use CComment, to help me do that, but what it does is just
/* comments go here */
/* multiple
lined
comment*/
Which is ugly. VVDocumentor doesn't help either because if one hits enter the result is
/*
* multiple
* lined
* comment
new comment here
*/
Which is unhelpful.
I'd like to modify Xcode such that the behavior of hitting enter takes this.
/*
* multiple
* lined
* comment
*/
to this
/*
* multiple
* line
* comment
* new comment line here
*/
I'm aware that you can simply block comment, by selecting text and pressing ⌘ + /, but that doesn't achieve what I'm looking for, and more importantly when I'm commenting I must press it again every time I press enter.
I'm sure someone else is looking for this since it's a pretty common style however my google-fu has failed thus far.
In C#, is there a reason why multi-line /* */ comments can't overlap? This also applies to HTML (and I'm sure lots of other languages) too.
e.g.
/*
int a = SomeFunction();
/* int i = 0; */
int b = SomeFunction();
*/
won't compile.
When writing code I often want to quickly check the logic, and isolate certain parts by removing a section using multi-line comments, but then have to go through the code block replacing all multi-line comments with single line ones //.
I don't like using single line comments to comment-out code blocks (even though Visual Studio provides shortcuts to do this) as these then affect text comments when it comes to removing all comments in the block using the shortcut.
Is there a reason why the multi-line comment cannot mean: 'ignore everything between here'?
I'm afraid this is the way how it's designed.
I think you should use single line comments as much as possible. It's also much clearer when you are viewing the history of a file in source control. If you commented an entire method with /* */ then only two lines will appear changed, otherwise the entire method will have been changed (// added).