How to add comments to fenced code block within doxygen documentation - documentation

I am using fenced code blocks in Doxygen using the markdown syntax. This makes it easy to add a simple code example, like this:
~~~~~{.cpp}
void doSomething()
{
}
~~~~~
When I try to add comments into the fenced code block using two forward slashes, Doxygen seems to remove the slashes. So when I write this:
~~~~~{.cpp}
void doSomething()
{
// This function should do something
}
~~~~~
I get this output:
void doSomething()
{
This function should do something
}
How can I tell Doxygen to keep the comments in the fenced code block?
EDIT:
The complete file looks like this (we use the standard Doxygen extension of .dox for documentation-only files):
/*!
\page PATTERN_SAMPLE Sample
~~~~~{.cpp}
void doSomething()
{
// This function should do something
}
~~~~~
*/
The result looks like this:

Try with \code
\code{.cpp}
class Cpp {};
\endcode

I encountered the same issue. No need to change code format. You can specify STRIP_CODE_COMMENTS as NO: this setting outputs the source code with the comment.
# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any
# special comment blocks from generated source code fragments. Normal, C++ and
# Fortran comments will always remain visible.
# The default value is: YES.
STRIP_CODE_COMMENTS = NO

Related

How to properly log Vulkan result type strings

Logging VkResult enum values
The VkResult enum contains a lot of values. Unfortunately though, they are C enums which aliases an integer, so I cannot easily just log their names to the console. For this purpose, I am envisioning a function which does something like this:
void graphics::log_vk_result(VkResult result)
{
switch (result)
{
case VK_SUCCESS:
log_core_debug("VK_SUCCESS"); return;
case VK_NOT_READY:
log_core_debug("VK_NOT_READY"); return;
[...]
}
But some of the enum values are only supported by certain extensions, as indicated here. An example: The extension VK_EXT_debug_report introduces the following value to the enumeration: VK_ERROR_VALIDATION_FAILED_EXT. So my idea for (potentially) more portable code would be something like this:
void graphics::log_vk_result(VkResult result)
{
switch (result)
{
[...]
#if defined(VK_EXT_DEBUG_REPORT_EXTENSION_NAME)
case VK_ERROR_VALIDATION_FAILED_EXT:
log_core_debug("VK_ERROR_VALIDATION_FAILED_EXT");
#endif
}
I found this name by looking at the extension manual page. I cannot easily see whether or not VK_EXT_DEBUG_REPORT_EXTENSION_NAME is a macro or an enum - it is a const char* but stated under the section "New Enum Constants". So checking for this particular value, for this particular extension, was my default choice.
[I do realize this extension is marked as deprecated, and I'm not using it! I only use it as an example here.]
I have two questions:
Is this needed?
Is this the correct way of doing this?
Thanks a lot!
All of this is unnecessary, since Vulkan SDK already includes the desired functionality:
#include <vulkan/vk_enum_string_helper.h>
void graphics::log_vk_result( const VkResult result ){
log_core_debug( string_VkResult(result) );
}

Found 'UR'-anomaly for variable

I have this sonar error Major:
Found 'UR'-anomaly for variable 'language' (lines '83'-'85')
in this function:
public void saveAll(List<Language> languages){
//Found 'UR'-anomaly for variable 'country' (lines '83'-'85').
//Code Smell Major Open Not assigned 20min effort Comment
for (Language language: languages) {
save(language);
}
}
how to fix this major error please, thanks for advance
Edit:
Found even more information it this other SO post. While that is more PMD centric, the background information can be of interest to you.
Java for each loop being flagged as UR anomaly by PMD.
This is a rule from PMD it seems. Definition:
The dataflow analysis tracks local definitions, undefinitions and
references to variables on different paths on the data flow. From
those informations there can be found various problems. 1. UR -
Anomaly: There is a reference to a variable that was not defined
before. This is a bug and leads to an error. 2. DU - Anomaly: A
recently defined variable is undefined. These anomalies may appear in
normal source text. 3. DD - Anomaly: A recently defined variable is
redefined. This is ominous but don't have to be a bug.
There is an open bug report for this:
https://sourceforge.net/p/pmd/bugs/1190/
In the example they report it for Arrays, but somebody commented that it happens for them also for collections.
Example:
public static void main(final String[] args) {
for (final String string : args) {
string.getBytes(); //UR Anomaly
}
for (int i = 0; i < args.length; i++) {
args[i].getBytes();
}
}
In our sonar setup we don't use this rule. Based on the available information you may wish not to use it in yours.

Clang Static Analyzis check Obj C code

I am trying to make a source code which I can check by Clang Static Analyzer.
I am fully newbie in Obj C so I don't know how can I use these small code parts.
Here is the checkers list:
http://clang-analyzer.llvm.org/available_checks.html#osx_checkers
osx.cocoa.AtSync (ObjC):
void test(id x) {
if (!x)
#synchronized(x) {} // warn: nil value used as mutex
}
I just need a 5-10 lines of code which I can test. I don't want to someone make codes for all checker, I just need an example for one.
Thanks!

How to include code excerpts using tags in asciidoc?

I can include the full Greet.java file
public class Greet {
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
from within the asciidoc file
== Hello Java
This is how one greets in Java:
[source,java]
.Greet.java
----
include::Greet.java
----
producing the documentation
But suppose that I only want to include an excerpt from the code delimited by tags. In the code above, suppose I only want to include the main function.
I don't see symbolic tags in the documentation, but this page suggests that it's sufficient to write
public class Greet {
// tag::helloMethod[]
public static void main(String[] args) {
System.out.println("Hello World!");
}
// end::helloMethod[]
}
and
== Hello Java
This is how one greets in Java:
[source,java]
.Greet.java
----
include::Greet.java[tags=helloMethod]
----
That just produces:
Can you suggest a method that would include just the excerpt? I'm using asciidoc 8.6.9.
What you're doing should work fine in Asciidoctor (the Ruby implementation of AsciiDoc), but not AsciiDoc (the Python implementation).
Notice though the different mechanism for obtaining syntax highlighting.
To get syntax highlighting with asciidoc one uses a command-line switch asciidoc -a source-highlighter=pygments file.adoc.
No command-line switch is needed (or possible) with Asciidoctor. With AsciiDoctor syntax highlighting is obtained by:
Inserting :source-highlighter: pygments at the top of each source file, and
Running sudo gem install pygments.rb to install pygments.
The Asciidoctor tags option can include multiple tags as well;
[tags="tag 1, tag 2, …"]
Bringing in more code excerpts in one go…

Can I give better names to value-parameterized tests in gtest?

I use value-parameterized tests in gtest. For example, if I write
INSTANTIATE_TEST_CASE_P(InstantiationName,
FooTest,
::testing::Values("meeny", "miny", "moe"));
then in the output I see test names such as
InstantiationName/FooTest.DoesBlah/0 for "meeny"
InstantiationName/FooTest.DoesBlah/1 for "miny"
InstantiationName/FooTest.DoesBlah/2 for "moe"
Is there any way to make these names more meaningful? I'd like to see
InstantiationName/FooTest.DoesBlah/meeny
InstantiationName/FooTest.DoesBlah/miny
InstantiationName/FooTest.DoesBlah/moe
INSTANTIATE_TEST_CASE_P accepts an optional 4th argument which can be used for this purpose. See https://github.com/google/googletest/blob/fbef0711cfce7b8f149aac773d30ae48ce3e166c/googletest/include/gtest/gtest-param-test.h#L444.
This is now available in INSTANTIATE_TEST_SUITE_P.
The optional last argument to INSTANTIATE_TEST_SUITE_P() allows the
user to specify a function or functor that generates custom test name
suffixes based on the test parameters.
Of interest is also this section in the source:
// A user can teach this function how to print a class type T by
// defining either operator<<() or PrintTo() in the namespace that
// defines T. More specifically, the FIRST defined function in the
// following list will be used (assuming T is defined in namespace
// foo):
//
// 1. foo::PrintTo(const T&, ostream*)
// 2. operator<<(ostream&, const T&) defined in either foo or the
// global namespace.
Two ways: (http://osdir.com/ml/googletestframework/2011-09/msg00005.html)
1) Patch the existing PrettyUnitTestPrinter to print test names; something like:
--- a/gtest-1.7.0/src/gtest.cc
+++ b/gtest-1.7.0/src/gtest.cc
## -2774,6 +2774,7 ## void PrettyUnitTestResultPrinter::OnTestCaseStart(const TestCase& test_case) {
void PrettyUnitTestResultPrinter::OnTestStart(const TestInfo& test_info) {
ColoredPrintf(COLOR_GREEN, "[ RUN ] ");
PrintTestName(test_info.test_case_name(), test_info.name());
+ PrintFullTestCommentIfPresent(test_info);
printf("\n");
fflush(stdout);
}
2) Write a new TestListener to print test results however you like. (https://code.google.com/p/googletest/source/browse/trunk/samples/sample9_unittest.cc) GTest allows registering a new test listener (and un-registering the builtin default), allowing pretty flexible customization of test output. See the link for example code.