Doxygen repeating text - doxygen

In all my APIs I have a line of text that gets repeated. Is there a way to put that text in one place and link to it from the APIs?
For instance, in the below example, how to put the 'text that is common for many APIs' in one place, instead of writing the same thing in all the APIs?
/**
* #brief Function description
* #param [in] param function param description
* #return return description
*
* #attention text that is common for many APIs
***********************************************************************/
int func(int param);

In case it is always the same line, best would be to define a special command for it by means of and alias in the doxygen configuration file (Doxyfile), see the tag ALIASES
For longer texts the doxygen command \includedoc would be the way to go.

Related

PostgreSQL, Pl/pgsql - How to access a query string that executed the stored procedure i'm in?

is there a way to access the query string from within a stored procedure?
i mean i'd like to add some debugging to a lot of stored procedures and it would be brilliant if i had some constant accessible from the body of the procedure, which had the query string.
something which would work with EXECUTE.
i've read the docs and cannot see anything like that...
thanks!
I agree with Pavel that your requirement is not real clear. However, I guess that you want the to get the statement that called the procedure currently running. If so then there may be a built in function: Current_Query(). Following is an example of its use.
create or replace function what_called_me()
returns text
language sql
as $$
select current_query();
$$;
select 1 num, 'A' col, what_called_me() sql_statement;
I don't understand well, what you need, but maybe you need plpgsql plugin API. This API is not well documented, but there is lot of PostgreSQL extensions that use this API - PLdebugger, plpgsql_chec, plprofiler and maybe other.
/*
* A PLpgSQL_plugin structure represents an instrumentation plugin.
* To instrument PL/pgSQL, a plugin library must access the rendezvous
* variable "PLpgSQL_plugin" and set it to point to a PLpgSQL_plugin struct.
* Typically the struct could just be static data in the plugin library.
* We expect that a plugin would do this at library load time (_PG_init()).
* It must also be careful to set the rendezvous variable back to NULL
* if it is unloaded (_PG_fini()).
*
* This structure is basically a collection of function pointers --- at
* various interesting points in pl_exec.c, we call these functions
* (if the pointers are non-NULL) to give the plugin a chance to watch
* what we are doing.
*
* func_setup is called when we start a function, before we've initialized
* the local variables defined by the function.
*
* func_beg is called when we start a function, after we've initialized
* the local variables.
*
* func_end is called at the end of a function.
*
* stmt_beg and stmt_end are called before and after (respectively) each
* statement.
*
* Also, immediately before any call to func_setup, PL/pgSQL fills in the
* error_callback and assign_expr fields with pointers to its own
* plpgsql_exec_error_callback and exec_assign_expr functions. This is
* a somewhat ad-hoc expedient to simplify life for debugger plugins.
*/
typedef struct PLpgSQL_plugin
{
/* Function pointers set up by the plugin */
void (*func_setup) (PLpgSQL_execstate *estate, PLpgSQL_function *func);
void (*func_beg) (PLpgSQL_execstate *estate, PLpgSQL_function *func);
void (*func_end) (PLpgSQL_execstate *estate, PLpgSQL_function *func);
void (*stmt_beg) (PLpgSQL_execstate *estate, PLpgSQL_stmt *stmt);
void (*stmt_end) (PLpgSQL_execstate *estate, PLpgSQL_stmt *stmt);
/* Function pointers set by PL/pgSQL itself */
void (*error_callback) (void *arg);
void (*assign_expr) (PLpgSQL_execstate *estate, PLpgSQL_datum *target,
PLpgSQL_expr *expr);
} PLpgSQL_plugin;
This is necessary when you really need to detail info about what is inside.
Maybe you need information just about executed queries - then you can look on extension auto_explain, when you set auto_explain.log_nested_statements to on, then the queries from procedure will be logged.

JSDoc: make param required/optional based on another param

I have two parameters, limit and page. If page is passed, limit is required. Otherwise, limit is optional. Below is my current JSDoc. How can I modify it (if this is possible) to properly show the relationship between the two?
/**
* ...
* #param {Number} [ctx.request.body.limit] A limit on the number of items to return
* #param {Number} [ctx.request.body.page] The page we are currently on. A `limit` must also be
* given when using this parameter
*/

Doxygen - how to document a variable so I can see its type

I'm sorry if it sounds too simple a question but still ...
I am documenting php code and whereas all functions etc. look good in the generated documentation,
I have problems with variable types which should be visible in the generated documentation.
I document them in this way:
/**
* $request - request object
*
* #type int
* #access private
*/
private $request;
As a result, I can see 'int' in the generated documentation, but #type is not a correct command. The proper command would be #var instead of #type but then I cannot see the type of the variable in the documentation.
So the question is "How to document a variable so I can see its type?"
Please help :)

Confluence 5 User Macro parameters limitations?

I'm writing a User Macro in Confluence 5 and I found that the 10th parameter is not being interpreted.
This is my macro header:
## #param ArtifactVersion:title=Artifact Version|type=string|required=true
## #param Contacts:title=Contacts|type=string|required=true
## #param Date:title=Date|type=date|required=true
## #param RollbackVersion:title=Rollback Version|type=string|required=true
## #param QaEngineer:title=QA Engineer|type=string|required=false
## #param ArtifactId:title=Artifact Id|type=string|required=true
## #param SiteName:title=Site Name|type=string|required=true
## #param Servers:title=Servers|type=string|required=true
## #param Instance:title=Instance|type=enum|enumValues=0,1,2,3,4,5,6,7,8,9,10|required=true
## #param MyParam:title=My Param|type=string|required=true
If I add another param (MyParam) then it is not being interpreted. It just prints $paramMyParam literally.
I'm fairly certain that there is an underlying limitation of 9 params in Confluence user macros. Whether or not this is a deliberate design decision, a limitation of the underlying architecture, or simply an oversight/bug, I cannot say.
If this is a deal-breaker for your macro, you could consider re-writing it as a fully-fledged Macro module using a Java plugin.
I am not certain you can have the 10th parameter, but I believe you could combine 2 parameters into 1 to allow room for the last one.
Artifact version and Artifact ID sound like they could be parsed out of the same string, similar to the way you would do so for the list of servers you have for your 8th parameter.

RequestFactoryEditorDriver#getPaths() usage?

HI: Below code is from RequestFactoryEditorDriver:
/**
* Returns a new array containing the request paths.
*
* #return an array of Strings
*/
String[] getPaths();
My question is,
When and in what place to use this method, there is no place to set paths to the RequestFactoryEditorDriver, is the paths generated when creating the driver? if so, what's the rule of "generating paths"?
I think the client should provide the paths themselves, such as:
factory.find( proxyId ).with( myPaths).fire(...)
other than from RequestFactoryEditorDriver#getPaths(), if the paths get from 1 is not specified.
The paths are computed from the editor hierarchy. The list basically includes all the properties being edited that are not simple values (primitives, strings, dates, etc.)
If you have the following:
TextBox name;
DateBox dateOfBirth;
#Path("manager.name")
Label managerName;
AddressEditor address;
getPaths would return "manager", "address".
The idea is that you can pass the value directly to with() and you'll retrieve all the objects needed by the editor. If you add or remove a subeditor down the hierarchy, you don't have to change your request code, the getPaths value will be different and contain what's needed by the editor.