Do you have any visual assist macros that you write and you want to share?
it can be very useful on coding..
people who use Visual-Assist knows that..
I don't have all that much to share, but I like these doxygen macros that pop up when I type /**:
/** $end$ */
/**
* $end$
*
*/
/**
* \brief $end$
*
* \details
*
*
* \notes
*/
And this one when I type /*<
/**< $end$ */
Oh, and I like this for #p:
#pragma message(MESSAGE_ORIGIN "<$end$>")
(MESSAGE_ORIGIN is a macro that expands to filename and line in the way the compiler emits it, so you can click on messages in the IDE's output pane.)
In a shop I worked for, we had the policy to leave remark in the code with date and author. For this, the following was useful:
// $YEAR$-$MONTH_02$-$DAY_02$ sbi: $end$
just wanted to share macro for vector
unsigned int length = $vectorName$.size();
for (unsigned int $Index$ = 0; $Index$ < length ; $Index$++)
{
$end$
}
a macro for class creation. but the filename and class name should be same..
#ifndef _$FILE_BASE_UPPER$_H_
#define _$FILE_BASE_UPPER$_H_
namespace $NAMESPACE$
{
/*
* Class $FILE_BASE$
*/
class $FILE_BASE$ : public $BASE_CLASS$
{
public:
$FILE_BASE$();
virtual ~$FILE_BASE$();
$end$
protected:
$end$
private:
};
}
#endif // _$FILE_BASE_UPPER$_H_
/**
* \file $FILE_BASE$.$FILE_EXT$
* \brief
* \author
* \date $DATE$
*/
#ifndef __$FILE_BASE_UPPER$_$FILE_EXT_UPPER$_INCLUDED__
#define __$FILE_BASE_UPPER$_$FILE_EXT_UPPER$_INCLUDED__
$end$
#endif //__$FILE_BASE_UPPER$_$FILE_EXT_UPPER$_INCLUDED__
Related
I want to document a macro like
HELPS(enumName, uint8_t, element1 = 4, element2, last);
with Doxygen and convert it with the preprocessor to
enum class enumName
{
element1 = 4,
element2,
last
};
to get a common enum documentation.
I used already the PREDEFINED tag in doxygen with
HELPS(param1,param2,...)="enum class param1 { __VA_ARGS__ }"
but this won't work.
Doxygen version is 1.9.1
Language is C++.
I usually document enum classes like
/**
* #enum enumName
* #brief a enum test class
* #var enumName::element1
* It is 4
* #var enumName::element2
* It is 5
* #var enumName::last
* It is 6
*/
enum class enumName
{
element1 = 4,
element2,
last
};
which works pretty well.
For some reasons I am now forced to use a Macro (HELPS) and not a enum. The behaviour is the same and the documentation shoulb be as well.
I wrote:
/**
* #enum enumName2
* #brief a enum test class
* #var enumName2::element10
* It is 40
* #var enumName2::element20
* It is 41
* #var enumName2::last
* It is 42
*/
HELPS(enumName2, uint8_t, element10 = 40, element20, last);
which should expand in the doxygen preprocessor to the good working example aboth but sadly (with -d Preprocessor) it expands to:
/**
* #enum enumName2
* #brief a enum test class
* #var enumName2::element10
* It is 40
* #var enumName2::element20
* It is 41
* #var enumName2::last
* It is 42
*/
element10 = 40 class enumName2 { __VA_ARGS__ } element20, last);
which results in a bad documentation.
Any suggestions?
I have been struggling with getting the below code excerpt's documentation appear properly with doxygen.
I have searched online for the problem; yet, it seems that the documentation not showing up is mostly due to the member function/variable being private. Even though I seem to be documenting a public member function, which is also non-static, I can't get doxygen working properly. I would appreciate any help of yours.
/**
* #brief Algorithm abstraction.
*
* #tparam float_t `float` or `double`.
* #tparam int_t `int64_t` or similar.
* #tparam StepPolicy Policy for selecting a step-size.
* #tparam OraclePolicy Policy for getting first-order information.
*/
template <class float_t, class int_t, template <class, class> class StepPolicy,
template <class, class> class OraclePolicy>
struct Algorithm : public StepPolicy<float_t, int_t>,
public OraclePolicy<float_t, int_t> {
/**
* #brief Default constructor.
*
*/
Algorithm() = default;
/**
* #brief Constructor with a step-size.
*
* #param[in] step Non-negative step-size value.
*/
Algorithm(float_t step) : StepPolicy<float_t, int_t>{step} {}
/**
* #brief Set the initial step-size of the algorithm.
*
* #param[in] step Non-negative step-size value.
*/
void set_stepsize(float_t step) { StepPolicy<float_t, int_t>::set(step); }
/**
* #brief Get the current step-size of the algorithm.
*
* This does *not* change the state of StepPolicy.
*
* #return float_t Current step-size.
*/
float_t get_stepsize() const { return StepPolicy<float_t, int_t>::get(); }
/**
* #brief Get current step-size based on the algorithm's state.
*
* #param[in] k Current iteration count.
* #param[in] N Dimension of `x` and `dx`.
* #param[in] x Current decision vector.
* #param[in] dx Current first-order information.
* #return float_t Current step-size.
*/
float_t get_stepsize(const int_t k, const int_t N, const float_t *x,
const float_t *dx) {
return StepPolicy<float_t, int_t>::get(k, N, x, dx);
}
private:
int_t k{0};
};
I am not sure if doxygen has anything to do with valid code excerpts, but the above code does indeed compile. Does it have anything to do with templates and inheritance? Am I missing something? I mean, for non-inheriting template classes, doxygen can do its job.
By the way, I do not have any concrete StepPolicy or OraclePolicy somewhere in my directories. Moreover, I can see the constructors getting documented properly. I am just stuck.
I can share my Doxygen file here, which is basically just the defaults overridden in MathJax-related settings.
Thank you, in advance, for your time.
Starting with v1.8.14, there is no such a problem. Apparently, the question was a bug, which has been fixed by the maintainers of doxygen.
I understand that we can use \defgroup key word to define a group in doxygen and add the class in this group by using key word \addtogroup. My question is how can I refer to this group in the documentation. For example,
/**
* \defgroup abc abc
*/
/**
* \addtogroup auxiliary_functions
* #{
*/
/**
* Introduction to A.
*/
class A
{
};
/*
* #}
*/
Then, in a page section, how can refer abc group?
/** #page tttt
* how to refer to group abc?
*
*/
You can reference any group by using its label. In your case, to reference the abc group from page ttt use the following
/** #page tttt
*
* For more information, please see #ref abc
*/
The resulting page will contain a link to your group, the text of which will reflect the group's title (abc in your case).
As far as I know by using the keyword ingroup
/**
* \ingroup abc
* \brief Explain why
*/
extern int VarInA;
You can find more here: Grouping doc
http://www.doxygen.nl/manual/commands.html#cmdcopydoc
made some exclamatory mention of not using spaces in your #copydoc directive.
But what do you do when the source of the copy is an object that inherently contains spaces, such as:
class Base
{
public:
/**
* True if blah blah blah
*/
virtual operator bool() const = 0;
/**
* Messages about any rules that were broken
*/
virtual const std::vector<Err> & errors() const = 0;
...
class Derived : public Base
{
public:
/*! #copydoc Base::operator bool()
* This doesn't work.
*/
operator bool() const;
/*! #copydoc Base::errors()
* This does work.
*/
const std::vector<Err> & errors() const;
...
I also tried
/*! #copydoc SomeOtherClass::operatorbool()
and
/*! #copydoc SomeOtherclass::bool()
just as random guesses, but neither worked.
I've managed to solve this by defining the virtual method as follows:
virtual operatorbool()const = 0;
also you'll need this in your derived class:
/*! #copydoc Base::operatorbool
* random info here
*/
This is a possible bug, maybe this needs a ticket, unless I'm missing something...
This worked for doxygen 1.8.6.
I'm brand new to JSDoc, and I'm trying to figure out the best way to tag my code. For some reason after I label something as a #class, I can't get anything to appear as #inner:
/**
* The logger, to simply output logs to the console (or potentially a variable)
* #class Logger
* #requires 'config/globalConfig'
*/
define(["config/globalConfig"], function (config) {
/**
* Instantiate a new copy of the logger for a class/object
* #constructor
* #param name {string} - The name of the class instantiating the logger
*/
return function (name) {
/**
* #memberOf Logger
* #type {string}
*/
this.name = name;
/**
* Place the message on the console, only for "DEV" level debugging
* #function
* #memberOf Logger
* #param message {string}
*/
this.debug = function (message) {
... some code ...
};
};
});
Right now all the members are appearing as <static>. If I add the #inner tag to any of the attributes/functions they vanish completely from the output.
Edit: I also forgot to mention. The #constructor flag doesn't seem to be working either. If I remove that entire section, it appears the same in the output. The output does not include the #param that I would like to mention with my constructor.
Please let me know if this is completely off, I'm just kind of guessing here since the JSDoc3 documentation is a bit difficult to read.
So I figured it out, still not sure if it's absolutely correct. I had to use "Logger~name" to have it appear correctly as an inner function. According to the JSDoc documentation, this ~ is "rarely used". Seems to be the only thing that works for me.
define(["config/globalConfig"], function (config) {
/**
* The logger, to simply output logs to the console (or potentially a variable)
* #class Logger
* #param name {string} - The name of the class instantiating the logger
*/
return function (name) {
this.name = name;
/**
* Place the message on the console, only for "DEV" level debugging
* #function Logger~debug
* #param message {string}
*/
this.debug = function (message) {
... code ...
};
};
});