My client gave me unusual (and non-negotiable) requirement to provide them with dual-language (English and Polish) doxygen documentation from C++ code.
My first idea is to use conditional compilation for comments, like:
#if DOXYGEN_ENGLISH
/**
* #brief Sample method
*/
#elif DOXYGEN_POLISH
/**
* #brief Przykładowa metoda
*/
#endif
void foo();
Then run Doxygen twice with different base locale and predefined constant... and it actually works. But it's very cumbersome...
Have someone has an idea how can I improve this solution? Or solve it different way?
Doxygen has the build in command \~[langId] for handling different languages.
The above presented example could be formulated as:
/**
* \~english #brief Sample method
* \~polish #brief Przykladowa metoda
*/
void foo();
no direct requirement using a preprocessor / pre-processor directives / settings
only one place in the doxygen configuration file to be changed (Doxyfile) when switching language.
Related
With every new CCS-Version, I always search on how to activate documentation with Doxygen.
I think I'm not the only one, so I just wanted to show it to everyone again. (And for me if I have to install a never CCS again)
To use doxygen I am using the eclox-Plugin for eclipse.
The installation ist quite easy and described here https://anb0s.github.io/eclox/
But the tricky part is, how the activate the documentation while coding so that the documentation body for a function will automatically appear if you type /** one line above the function.
Inside CCS you have to go to Window->Preferences, make sure the advanced settings are displayed (button at the bottom). Then go to C/C++->Editor and change the property of the "Documentation tool comments" to Doxygen.
Now you can type /** over a function to automatically generate the documentation body like this.
/**
*
* #param pvData
* #param usLength
* #param ulStatusFlag
* #return
*/
uint16_t IPCLiteLtoRGetResult (void *pvData, uint16_t usLength, uint32_t ulStatusFlag)
Maybe this will help somebody (most likely myself) in the future.
is it possible to define something like macros in Doxygen?
I want write a comment something like this:
/**
\return return_self_reference
*/
and Doxygen will replace return_self_reference with a string defined by me.
The comment that would then be read by Doxygen would be this one:
/**
\return A reference to the instance that the operator was called on.
*/
Please note that, alltough I called it a macro earlier, I do not want to define a C macro or anything like that in the actual code.
Doxygen has for these cases the configuration parameter ALIASES.
Lets take the following example:
/** \file
*/
/**
* \return the normal version
*/
int fie0(void);
/**
* \return \str1_repl
*/
int fie1(void);
/**
* \str2_repl
*/
int fie2(void);
and set the following ALIASES in the doxygen configuration file (see also the manual for more possibilities of ALIASES):
ALIASES = "str1_repl=just the text in replacement" \
"str2_repl=\return return and the text in replacement"
and we will get the following result:
I'm trying to document a method and trying to use #link and #code as in JavaDoc.
I know in kotlin there is a kDoc but I can't find them or at least something similar.
#link and #code doesn't exist in kDoc but can easily be replaced by Inline Markup.
from KotlinDoc Linking to Elements
Inline Markup
For inline markup, KDoc uses the regular Markdown syntax, extended to
support a shorthand syntax for linking to other elements in the code.
Linking to Elements
To link to another element (class, method, property or parameter),
simply put its name in square brackets:
Use the method [foo] for this purpose.
If you want to specify a custom
label for the link, use the Markdown reference-style syntax:
Use [this method][foo] for this purpose. You can also use qualified
names in the links. Note that, unlike JavaDoc, qualified names always
use the dot character to separate the components, even before a method
name:
Use [kotlin.reflect.KClass.properties] to enumerate the properties of
the class. Names in links are resolved using the same rules as if the
name was used inside the element being documented. In particular, this
means that if you have imported a name into the current file, you
don't need to fully qualify it when you use it in a KDoc comment.
Note that KDoc does not have any syntax for resolving overloaded
members in links. Since the Kotlin documentation generation tool puts
the documentation for all overloads of a function on the same page,
identifying a specific overloaded function is not required for the
link to work.
For {#link SomeClass} in Java maps to [SomeClass] in Kotlin
For {#code true} in Java maps to `true` in Kotlin
You can write your code with java and convert class into Kotlin.
/**
* #see link
*/
public class Some {
}
will be converted to
/**
* #see [link](http://somelink.com)
*/
class Some
The answer that Artur gave is a good hint in general, but the result is wrong. At least IntelliJ IDEA does not grok the result. The markdown link format using []() is fine in the main comment text, but not for external links in the #see tag. For those, you need the same syntax as in Java:
/**
* Do something.
*
* #see External links in kdoc
*/
I struggled with this for a bit with Android Studio 3.5.2 on Mac. This worked for me:
/**
* [Your fully-qualified class name.function name]
*/
If I didn't use the fully-qualified name Kdoc would complain that it was a unresolved reference. What I couldn't figure out is how to actually use the link itself. For that you need to press and hold the COMMAND key (on Mac) and then the links would be active.
To reference a method use the class:
/**
* When the configuration succeeds **[MyCallback.onConfigured]** is called.
*/
class MyClass(myCallback: MyCallback) {
Using a variable/parameter does not work:
/**
* When the configuration succeeds **[myCallback.onConfigured]** is called.
*/
class MyClass(myCallback: MyCallback) {
It seems we should just use a markdown hyperlink without any special tags such as #see or #link:
/**
* This is a doc.
*
* See [this](https://google.com)
* And [this](https://stackoverflow.com)
*/
fun myfun() {}
This doc renders in following way in IDE:
As for the #code you should use Markdown syntax (cause KDoc is an extended version of Markdown):
To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab.
/**
* Some code sample:
*
* Set<String> s;
* System.out.println(s);
*/
class Scratch
Sample how to leave links for classes:
/**
* [YourClass] Methods
* */
also with method calls
/**
* [YourClass.someMothod] Methods
* */
Real example:
/**
* [BaseActivity] Methods
* */
override fun initVars() {
//Just Sample
}
/**
* [MainContract.View] - Overrides
* */
override fun handleConnectionMassage(isShow: Boolean) {
//Just Sample
}
I've been reading very careful about grouing and ingroup command. It states that "Members of a group can be files, namespaces, classes, functions, variables, enums, typedefs, and defines, but also other groups."
As such, I've been trying to group few variables from inside the function. The documentation does not seem to state any specifications or limitation as to what kind of variable it is.
Here is simple example:
/// \file hyperLinks.h
class hyperLinks
{
public:
void getEnvVars();
// WORKS!
/**
* #ingroup group2
*/
int public_var;
protected:
// WORKS!
/**
* #ingroup group2
*/
int protected_var;
private:
int private_var;
};
// WORKS!
/**
* #ingroup group2
*/
int globalVarH;
And the corresponding cpp file:
/// \file hyperLinks.cpp
#include "hyperLinks.h"
/**
* #defgroup group2 The Second Group
* This is the second group
*/
hyperLinks::getEnvVars()
{
// do something here
// put this into a group2
// ---DOES NOT WORK---
/**
* #ingroup group2
* #brief variable inside getEnvVars()
*/
int inFunctionVariable;
}
// works!
/**
* #ingroup group2
* #brief OUTSIDE globalVar from .cpp file in group 2
* #brief outside class defenition
*/
int globalVarCPP;
From the code above the following DO get placed in Module->The Second Group:
-public_var
-protected_var
-globalVarH
-globalVarCPP
Yet, the variable from inside the function DOES NOT appear in the group:
-inFunctionVariable
The 5th variable is no showing up.
Any ideas why this is not working?
How to fix it or a work-around?
Also, I've read thru all the message/warning generated during the run of doxygen documentation.
There are errors or warning with regards to this file.
Any help will be greatly appreciated.
Thank you!
ps. Doxygen version 1.8.3.1
Doxygen doesn't support commenting elements within the body of a function. From Documenting the code in the doxygen Manual:
For each entity in the code there are two (or in some cases three) types of descriptions, which together
form the documentation for that entity; a brief description and detailed description, both are optional. For
methods and functions there is also a third type of description, the so called in body description, which
consists of the concatenation of all comment blocks found within the body of the method or function.
In your code example, the documentation on inFunctionVariable is in-body documentation for the hyperLinks::getEnvVars() function, and appears as a part of the documentation for that item.
How do I flag a function as being deprecated in an iOS Objective-C header file?
I'm guessing there's just some keyword I can stick after the function somewhere?
I would like for a compiler warning to be generated should anyone try and use the deprecated function, similar to the behavior seen in Apple's APIs.
Try appending an attribute to your method declaration:
- (void)fooBar __attribute__ ((deprecated));
Taken from here.
Instead of __attribute__((deprecated)), you can use use the macros defined in <cdefs.h>:
- (void)fooBar __deprecated;
// Or better:
- (void)fooBar __deprecated_msg("Use barFoo instead.");
Or you can use the macros defined in <AvailabilityMacros.h>:
- (void)fooBar DEPRECATED_ATTRIBUTE;
// Or better:
- (void)fooBar DEPRECATED_MSG_ATTRIBUTE("Use barFoo instead.");
If you use Objective-C, it makes no difference as you are going to use a modern compiler, so you can go for Apple short syntax __deprecated_msg(). But if you use C for cross-platform, then DEPRECATED_MSG_ATTRIBUTE() uses the optimal availability definitions (for instance, it supports GCC3.1).
Tim's answer will actually produce a compiler warning; the other versions are merely comments which have no effect w.r.t. the compiler.
If you look at /usr/include/AvailabilityMacros.h, you'll see how Apple does this. That header uses __attribute__((deprecated)) and __attribute__((unavailable)) depending on whether the API is present but deprecated, or has actually been removed from the OS.
From Apple's SFAuthorization.h:
/*!
DEPRECATED: Use obtainWithRight:flags:error:
#method permitWithRight:flags:
#abstract Call permitWithRight to gain a right to have
access to a privilege operation.
#param rightName The name of an authorization right.
#param flags Authorization flags.
*/
- (OSStatus)permitWithRight:(AuthorizationString)rightName
flags:(AuthorizationFlags)flags;
If you're not using an automated documentation builder I'd say something like this is enough:
- (void)doSomething; /* DEPRECATED */
You could also follow the HeaderDoc manual. Where this syntax is used:
/*!
* #abstract Foo is good for bar.
*
* #deprecated in version 2.0
*/