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?
Related
I'm a bit new to jsdocs, and I'm trying to properly document arrow functions.
Everything is fine until I add "export" at the beginning of the line, I saw multiple answers that recommended to add #module at the top and #memeberof in the documentation, but these options don't seem to work for me.
This is a sample of my code:
/** #module SampleModule */
/**
* Function description
*
* #param {string} _type - Component type.
* #param {string} currentName - Current component's name.
* #param {string} canonicalname - Current site.
* #returns {undefined}
*
* #example
*
* activateComponentWizard('t1', 'test 1', 'www.example.com')
*/
export const activateComponentWizard = async (_type, currentName, canonicalname) => { ... }
This is the result:
Any ideas what am I missing?
I have a parent class MapItem, and a child class, MapExhibit. My MapExhibit class has a property, $builiding, which ties the exhibit to a particular MapBuilding entity. When the API calls for the JSON, the $building should not appear for MapExhibit entities in particular.
Note I am using the willdurand/Hateoas bundle
Here is my current setup:
/**
* #ORM\Entity(repositoryClass="App\Repository\Map\MapItemRepository")
* #ORM\InheritanceType("JOINED")
* #ORM\DiscriminatorColumn(name="discr", type="string")
* #ORM\DiscriminatorMap({"item" = "MapItem", "bathroom" = "MapBathroom", "building" = "MapBuilding", "bus" = "MapBus", "emergency" = "MapEmergency", "exhibit" = "MapExhibit", "parking" = "MapParking"})
* #Serializer\XmlRoot("mapItem")
* #Hateoas\Relation("self", href = "expr('/api/mapitems/' ~ object.getId())")
*/
abstract class MapItem
{
/**
* #ORM\Id
* #ORM\GeneratedValue
* #ORM\Column(type="integer")
* #Serializer\XmlAttribute
*/
private $id;
...
}
/**
* #ORM\Entity(repositoryClass="App\Repository\Map\MapExhibitRepository")
*
* #Hateoas\Relation(
* "building",
* exclusion = #Hateoas\Exclusion()
* )
*/
class MapExhibit extends MapItem
{
...
/**
* Many emergency devices can belong to one building.
* #ORM\ManyToOne(targetEntity="MapBuilding", inversedBy="emergencyDevices")
* #ORM\JoinColumn(name="building_id", referencedColumnName="id", nullable=true, onDelete="SET NULL")
*/
private $building;
...
public function getBuilding(): ?MapBuilding
{
return $this->building;
}
}
The result is a JSON object that includes the relation from the parent MapItem
"_links":{"self":{"href":"\/api\/mapitems\/29"}}}]
But also includes the data from the exhibit's building. This part should be ignored.
Take a look on exclusion strategies in documentation.
If you would like to always expose, or exclude certain properties. Then, you can do this with the annotations #ExclusionPolicy, #Exclude, and #Expose.
The default exclusion policy is to exclude nothing. That is, all properties of the object will be serialized. If you only want to expose a few of the properties, then it is easier to change the exclusion policy, and only mark these few properties: (...)
So basically, put #Serializer\Exclude() above private $builidng. Don't forget to add use JMS\Serializer\Annotation as Serializer; on top.
How can I document possible configuration properties in function argument in JSDOC:
/**
* N level expectimax AI.
*
* #param {object} cfg config
* cfg.minimaxDepth - limit for minimax search
* cfg.expectiDepth - limit for expectimax search
* cfg.weightFn - position weight function
*
* #constructor
*/
function expectimaxAI(brdEngine, cfg) { ... }
Which markup is to use for cfg.minimaxDepth (cfg.*) parameters?
Is it possible to document synthetic aiCfg type and put reference to it as:
* #param {aiCfg} cfg config
or somehow else?
After reading official JSDoc 2.x docs I make some hack:
/**
* #name BlindWeightRandomCfg
* #function
* #param {number} left weight
* #param {number} right weight
* #param {number} up weight
* #param {number} down weight
*/
and refer to non-existing function as:
/**
* Blind weight random AI.
*
* #param {Board} brdEngine board engine from board.js
* #param {BlindWeightRandomCfg} cfg configuration settings
* #constructor
*/
ai.BlindWeightRandom = function(brdEngine, cfg) { ... }
Now argument cfg - clickable to definition of BlindWeightRandomCfg!
UPDATE Another possibility for JSDoc 2.x:
/**
* #name BlindWeightRandomCfg
* #namespace
* #property {number} left weight
* #property {number} right weight
* #property {number} up weight
* #property {number} down weight
*/
and for JSDoc 3.x:
/**
#typedef PropertiesHash
#type {object}
#property {string} id - an ID.
#property {string} name - your name.
#property {number} age - your age.
*/
/** #type {PropertiesHash} */
var props;
Seems that #typedef is a solution. Please see other variants and at official docs.
How to mark or make reference function argument in jsdoc/jsdoc3.
For example:
/**
* Build xxx.
* cfg is optional.
*
* #param {Object} cfg config
* #function
*/
function build(engine, cfg) { ... }
What markup used to wrap cfg in cfg is optional. description?
I see one possible way by enclosing into tt HTML tag:
/**
* Repeat <tt>str</tt> several times.
* #param {string} str The string to repeat.
* #param {number} [times=1] How many times to repeat the string.
* #returns {string}
*/
repeat: function(str, times) { ... }
I am getting this error in my annotations docblock for Doctrine 2:
Doctrine\Common\Annotations\AnnotationException: [Syntax Error] Expected PlainValue, got ')'
After looking for an answer I found this reference Stackoverflow Question 3500125 which in essence says to put quotes around all values in annotations.
With the annotation block I have this does not seem possible. here is my example that is throwing the error.
/**
* #var tags
*
* #ManyToMany(targetEntity="namespace\to\tag")
* #JoinTable(name="content_tag",
* joinColumns={
* #JoinColumn(name="content_id", referencedColumnName="id")
* },
* inverseJoinColumns={
* #JoinColumn(name="tag_id", referencedColumnName="id")
* }
* ) // This is the line indicated by the error
*/
private $tags;
If I follow the advice of the answer I found in stack overflow which is to quote out the values, my code will be like this:
/**
* #var tags
*
* #ManyToMany(targetEntity="namespace\to\tag")
* #JoinTable(name="content_tag",
* joinColumns="{
* #JoinColumn(name="content_id", referencedColumnName="id")
* }",
* inverseJoinColumns="{
* #JoinColumn(name="tag_id", referencedColumnName="id")
* }" // Note the extra quotation marks
* )
*/
private $tags;
Which is not right at all.
For people who have come here but not because of doctrine, my mistake was using single quotes instead of double quotes in the #Routes annotation.
WRONG:
/**
* #Route('/home')
*/
RIGHT
/**
* #Route("/home")
*/
It was a silly mistake, the error string was not very helpful as it pointed to the line i showed in my question as the line that the error was on. The fact was that this entity was extending a parent object, the parent had the #Entity tag but the child did not, i moved it and everything works fine.
I Just had the same kind of error by using an assert for an entity :
* #Assert\Email(
* message = "The email '{{ value }}' is not a valid email.",
* mode = 'strict',
* normalizer = 'trim'
* )
Turning it into
* #Assert\Email(
* message = "The email '{{ value }}' is not a valid email.",
* mode = "strict",
* normalizer = "trim"
* )
Fixed it :)