Is there a good/common way to mention the date of the last refactoring/update/review of a code ?
Expected example:
/**
* \author Caduchon
* \brief Example class
* \date April 2016
* \lastreview 2017-10-09
*/
class Example {};
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
I'm fairly new to using class libraries in PHP. I have the PHPSQLParser from https://code.google.com/archive/p/php-sql-parser/
My code looks like this:
myProgram.php
<?php
header('Content-Type: application/json');
require_once($_SERVER['DOCUMENT_ROOT'] . '/../PHP/includes/PHP-SQL-Parser/src/PHPSQLParser/PHPSQLParser.php');
$sql='SELECT description FROM model WHERE ModelId = "79876"';
$parser = new PHPSQLParser($sql);
echo json_encode($parser->parsed);
?>
I'm getting the following error:
PHP Fatal error: class 'PHPSQLParser' not found in myProgram.php on line 5
I know the require_once() is working because (1) I'm not getting an error from it, and (2) I temporarily inserted (and have since removed) an echo "hello"; in the class file and it did echo the phrase.
I'm not sure how to resolve the error. What should I be looking for here?
The class file for PHPSQLParser is as below:
PHPSQLParser.php
<?php
/**
* PHPSQLParser.php
*
* A pure PHP SQL (non validating) parser w/ focus on MySQL dialect of SQL
*
* PHP version 5
*
* LICENSE:
* Copyright (c) 2010-2014 Justin Swanhart and André Rothe
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. The name of the author may not be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* #author André Rothe <andre.rothe#phosco.info>
* #copyright 2010-2014 Justin Swanhart and André Rothe
* #license http://www.debian.org/misc/bsd.license BSD License (3 Clause)
* #version SVN: $Id: PHPSQLParser.php 1327 2014-04-15 11:17:49Z phosco#gmx.de $
*/
namespace PHPSQLParser;
use PHPSQLParser\positions\PositionCalculator;
use PHPSQLParser\processors\DefaultProcessor;
use PHPSQLParser\utils\PHPSQLParserConstants;
require_once dirname(__FILE__) . '/positions/PositionCalculator.php';
require_once dirname(__FILE__) . '/processors/DefaultProcessor.php';
require_once dirname(__FILE__) . '/utils/PHPSQLParserConstants.php';
/**
* This class implements the parser functionality.
*
* #author Justin Swanhart <greenlion#gmail.com>
* #author André Rothe <arothe#phosco.info>
* #license http://www.debian.org/misc/bsd.license BSD License (3 Clause)
*/
class PHPSQLParser {
public $parsed;
/**
* Constructor. It simply calls the parse() function.
* Use the public variable $parsed to get the output.
*
* #param String $sql The SQL statement.
* #param boolean $calcPositions True, if the output should contain [position], false otherwise.
*/
public function __construct($sql = false, $calcPositions = false) {
if ($sql) {
$this->parse($sql, $calcPositions);
}
}
/**
* It parses the given SQL statement and generates a detailled
* output array for every part of the statement. The method can
* also generate [position] fields within the output, which hold
* the character position for every statement part. The calculation
* of the positions needs some time, if you don't need positions in
* your application, set the parameter to false.
*
* #param String $sql The SQL statement.
* #param boolean $calcPositions True, if the output should contain [position], false otherwise.
*
* #return array An associative array with all meta information about the SQL statement.
*/
public function parse($sql, $calcPositions = false) {
$processor = new DefaultProcessor();
$queries = $processor->process($sql);
// calc the positions of some important tokens
if ($calcPositions) {
$calculator = new PositionCalculator();
$queries = $calculator->setPositionsWithinSQL($sql, $queries);
}
// store the parsed queries
$this->parsed = $queries;
return $this->parsed;
}
/**
* Add a custom function to the parser. no return value
*
* #param String $token The name of the function to add
*
* #return null
*/
public function addCustomFunction($token) {
PHPSQLParserConstants::getInstance()->addCustomFunction($token);
}
/**
* Remove a custom function from the parser. no return value
*
* #param String $token The name of the function to remove
*
* #return null
*/
public function removeCustomFunction($token) {
PHPSQLParserConstants::getInstance()->removeCustomFunction($token);
}
/**
* Returns the list of custom functions
*
* #return array Returns an array of all custom functions
*/
public function getCustomFunctions() {
return PHPSQLParserConstants::getInstance()->getCustomFunctions();
}
}
?>
The class is within a namespace - use
$parser = new PHPSQLParser\PHPSQLParser($sql);
find out more at the manual here: http://php.net/manual/en/language.namespaces.php
*How to Document following function in JSDoc JS-Toolkit *
I want to document try and help method in this main function
but i did not figure it out how to do that.
/** Sample doc
* #class
* #constructor
* #name Sample
*/
var main=function(){
this.value="";
/** help function
* #param {String} Name
*/
this.help=function(name){
console.log('help me'+name);
}
/** help function
* #param {String} Name
*/
this.try=function(name){
console.log('try me'+name);
}
}
I just struggled with this for several hours. I tried:
#member
#augments
#method
#this
From the examples and tutorials I found, member functions and variables should appear in the output simply by having /** description/* comments above them, but I found that was not the case. Like you, I'm using standard JavaScript constructors, where this should be able to be inferred automatically due to the #constructor being in place. Maybe there's some wrinkle I'm not seeing.
In the end, I found two tags that worked for me, #name and#memberof. They both allow you to specify the object that the property is a member of. Using #name in this way is undocumented (at least, I didn't see it anywhere), but very straightforward. You'll also need to use #function.
Here's an example with the #name tag:
/** help function
* #name Sample.try
* #function
* #param {String} Name
*/
this.try=function(name){
console.log('try me'+name);
};
And here's an example with the #memberof tag:
/** help function
* #memberof Sample
* #function
* #param {String} Name
*/
this.try=function(name){
console.log('try me'+name);
};
As you can see the output is almost the same. The only difference that I see is that #memberof includes this. in the method name. For that reason I've settled on using #name.
The remaining issue is that the functions are per-instance, not <static>.
Hope this helps!