I have been using doxygen to generate html document for my project. And my generated documents contain a files tab. How could I remove protected attribute and protected member function fields from it?
Protected Member Functions
Protected Attributes
If you do not wish something to be extracted it should not have a documentation block. In your release provide a header file that has only the methods you wish to be exposed, create a separate header file for your own use. You may also use the \internal flag if you want internal documentation for your benefit, however this would also require that the prototype for hidden methods be exposed.
In general:
/** \internal My personal documentation
* Public documentation..................
*/
doxyfile
EXTRACT_ALL= 0,
HIDE_UNDOC_MEMBERS= 1,
INTERNAL_DOCS = 1 or 0
Related
I've applied the guidance on programmatic usage of M2Doc (also with this help) to successfully generate a document via the API, which was previously prepared by using the M2Doc GUI (configured .docx plus a .genconf file). It seems to also work with a configured .docx, but without a .genconf file.
Now I would like to go a step further and ease the user interface in our application. The user should come with a .docx, include the {m:...} fields there, especially for variable definition, and then in our Eclipse application just assign model elements to the list of variables. Finally press "generate". The rest I would like to handle via the M2Doc API:
Get list of variables from the .docx
Tell M2Doc the variable objects (and their types and other required information, if that is separately necessary)
Provide M2Doc with sufficient information to handle AQL expressions like projectmodel::PJDiagram.allInstances() in the Word fields
I tried to analyse the M2Doc source code for this, but have some questions to achieve the goal:
The parse/generate API does not create any config information into the .docx or .genconf files, right? What would be the API to at least generate the .docx config information?
The source code mentions "if you are using a Generation" - what is meant with that? The use of a .genconf file (which seems to be optional for the generate API)?
Where can I get the list of variables from, which M2Doc found in a .docx (during parse?), so that I can present it to the user for Object (Model Element) assignment?
Do I have to tell M2Doc the types of the variables, and in which resource file they are located, besides handing over the variable objects? My guess is no, as using a blank .docx file without any M2Doc information stored also worked for the variables themselves (not for any additional AQL expressions using other types, or .oclAsType() type castings).
How can I provide M2Doc with the types information for the AQL expressions mentioned above, which I normally tell it via the nsURI configuration? I handed over the complete resourceSet of my application, but that doesn't seem to be enough.
Any help would be very much appreciated!
To give you an impression of my code so far, see below - note that it's actually Javascript instead of Java, as our application has a built-in JS-Java interface.
//=================== PARSING OF THE DOCUMENT ==============================
var templateURIString = "file:///.../templateReqs.docx";
var templateURI = URI.createURI(templateURIString);
// canNOT be empty, as we get nullpointer exceptions otherwise
var options = {"TemplateURI":templateURIString};
var exceptions = new java.util.ArrayList();
var resourceSetForModels = ...; //here our application's resource set for the whole model is used, instead of M2Doc "createResourceSetForModels" - works for the moment, but not sure if some services linking is not working
var queryEnvironment = m2doc.M2DocUtils.getQueryEnvironment(resourceSetForModels, templateURI, options);
var classProvider = m2doc.M2DocPlugin.getClassProvider();
// empty Monitor for the moment
var monitor = new BasicMonitor();
var template = m2doc.M2DocUtils.parse(resourceSetForModels.getURIConverter(), templateURI, queryEnvironment, classProvider, monitor);
// =================== GENERATION OF THE DOCUMENT ==============================
var outputURIString = "file:///.../templateReqs.autogenerated.docx";
var outputURI = URI.createURI(outputURIString);
variables["myVar1"] = ...; // assigment of objects...
m2doc.M2DocUtils.generate(template, queryEnvironment, variables, resourceSetForModels, outputURI, monitor);
Thanks!
No the API used to parse an generate don't modifies the template file nor the .genconf file. To modify the configuration of the template you will need to use the
TemplateCustomProperties class. That will allow you to register your metamodels and service classes. This instormation is then used to configure the IQueryEnvironment, so you might also want to directly configure the IQueryEnvironment in your code.
The generation in this context referes to the .genconf file. Note The genconf file is also an EMF model, so you can also craft one in memory to launch you generation if it's easier for you. But yes the use of a .genconf file is optional like in your code example.
To the list of variables in the template you can use the class TemplateCustomProperties:
TemplateCustomProperties.getVariables() will list the variables that are declared with their type
TemplateCustomProperties.getMissingVariables() to list varaibles that are used in the template but not declared
You can also find le list of used metamodels (EPackage nsURIs) and imported services classes.
The type of variables is not needed at generation time, it's only needed if you want to validate your template. At generation time you need to pass a map from the variable name to its value as you did in your example. The value of a variable can be a any object from your model (an EObject), a String, an Integer, ... If you want to use something like oclIsKindOf(pkg::MyEClass) you will need to register the nsURI of pkg first see the next point.
The code you provided should let you use something like projectmodel::PJDiagram.allInstances(). This service needs a ResourceSetRootEObjectProvider() that is initialized in M2DocUtils.getQueryEnvironment(). But you need to declare the nsURI of your metamodel in your template (see TemplateCustomProperties). This will register it in the IQueryEnvironment. You can also register it yourself using IQueryEnvironment.registerEPackage().
This should help you finding the missing parts in the configuration of the AQL environment. Your code seems good and should work when you add the configuration part.
When using C++ with doxygen I would like to add to the class description from within a function. I basically want to add information about the function calls I am making.
class_name.h
/**
* This is the overall description of the class
*/
class ClassName
{
...
}
class_name.cpp:
void ClassName::randomFunction()
{
/**
* #class ClassName
*
* calls testData on stuff (this should be appended to the class description)
*/
testData(stuff);
}
Doxygen output:
<b>Detailed Description</b>
<br>
This is the overall description of the class
<br>
calls testData on stuff
This method works when I put the comment outside of a function, but does not show up anywhere if I put it within randomFunction as the example shows. In the end, I would like the reader of the documentation to see a description of the class followed by the snippet that I have in the example. This makes it easier to keep my documentation in sync with the code and immediately tells the user about important functions that I am calling.
The reason I want to do this is to document the network messages that the class makes in one place instead of having the user search through documentation on multiple member functions.
EDIT:
doxygen version is 1.8.5
added clarification
The used version of doxygen (1.8.5, August 23, 2013) is a bit old and it is advised to update to the current version (1.8.17).
To have code snippets or documentation snippets in an other place as well doxygen has the command \snippet (see http://doxygen.nl/manual/commands.html#cmdsnippet).
To group information in different places doxygen has grouping commands like \defgroup (http://doxygen.nl/manual/commands.html#cmddefgroup), \ingroup (http://doxygen.nl/manual/commands.html#cmdingroup), \addtogroup (http://doxygen.nl/manual/commands.html#cmdaddtogroup).
See also the grouping chappetr in the doxgen documentation (http://doxygen.nl/manual/grouping.html).
After parsing, I want to get a meta-data of the source code's field, or method.
The purpose of this is to collect info of the source code after parsing.
In java, I used annotation.
After parsing, I find user-defined annotation on class, field, or method.
Under code is example.
#BizObject //By this annotation I could understand this class is related with bissness.
public class biz ... {
#DI //this field needs Dependency Injection.
public Logger logger;
}
By parsing, I want to collect user-specified meta-info of the source.
How user write the meta-data on the source code?? like java annotation.
I know in C++ there is no direct attribute for this purpose.
I just wondering how to mark meta-data indirectly using other things.
Self response.
I solved this problem by using attribute specifier.
It is similar to Java's annotation.
http://en.cppreference.com/w/cpp/language/attributes
http://www.codesynthesis.com/~boris/blog/2012/04/18/cxx11-generalized-attributes/
https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html
By using attribute specifier and CDT parser, I could get meta data related syntax's node.
CDT parser support GNU.
I have a project which contains an RPC-invokable API. The project also contains some other code. I'd like to generate a clean documentation just for these API functions (for users working with the API). Yet it should still be possible to generate a documentation of the whole program, intended for the developers.
The API is split into several classes ("command modules"). First thing I did is tell Doxygen to only look at those files, of course. But these classes also have some code which is not part of the API I'd like to generate the documentation for (helper functions).
These invokable functions ("commands") have a special return type: CommandResult.
As an example, here is such an API class:
class CommandModuleFoo {
int privateHelperFunction();
int privateMember;
public:
int publicHelperFunction();
int publicMember;
public slots:
/** Some documentation. */
CommandResult myFunction1(int someArg);
/** Some documentation. */
CommandResult myFunction2();
};
Now the documentation should basically contain the following:
class CommandModuleFoo
Public members:
CommandResult myFunction1(int someArg)
Some documentation.
CommandResult myFunction2()
Some documentation.
Question:
I know that I can select only a subset of the project's files by simply just naming them in the INPUT variable of my Doxyfile. But can I also select only a set of functions using a pattern?
Since I guess this is not possible, can I tell Doxygen to only generate documentation for one section? Doxygen has section markers: \if...\endif can be used to exclude some part of the document but include them with the configuration variable ENABLED_SECTIONS. But I need the opposite. Is there something like ONLY_SECTION?
Possible workarounds:
I could use above-mentioned section conditions around every code except the commands I want to document. But that sounds very ugly.
I could set HIDE_UNDOC_MEMBERS to YES in order to only generate documentation for documented members, but that would make it impossible to generate also a full documentation of the program, if one wants to. (i.e. it forbids to document non-API functions). Also, detecting undocumented API-functions is then more difficult.
I currently use the second workaround.
You could do the following:
Use \internal in the documentation of internal functions (the non-commands in this case):
/**
* \internal
* This helper function does foo.
*/
void myHelperFunction();
Your commands use normal doxygen comments:
/**
* Some documentation.
*/
CommandResult myFunction();
Then, in your Doxyfile use INTERNAL_DOCS = YES if you compile the documentation of the whole program and INTERNAL_DOCS = NO (default) to compile your API documentation.
Basically, treat your program like it was a library. Library developers often encounter this problem: they obviously want to have a clean documentation for the users of the library which only contains exported stuff, while they (probably) also want to have a more verbose documentation for developers of the library.
PS. You can also use \internal to selectively include paragraphs of the documentation of a function, i.e. your documentation for the developers could include some more detail which is not important for the users of your API. For details consult the documentation of \internal.
I created yaml configuration for Doctrine. When I'm trying doctrine orm:generate-entities, it creates php files with getters and setters in camel case. So, is_public field transforms into setIsPublic and getIsPublic methods. It's owful. How can I get set_is_public and get_is_public? I can manually edit generated php files, but I don't know what will happen when I change the schema.
You can choose a naming strategy that Doctrine will use to generate the items using:
Using a naming strategy you can provide rules for automatically
generating database identifiers, columns and tables names when the
table/column name is not given. This feature helps reduce the
verbosity of the mapping document, eliminating repetitive noise (eg:
TABLE_).
For your specific case, I think you're looking at something like:
$namingStrategy = new \Doctrine\ORM\Mapping\UnderscoreNamingStrategy(CASE_LOWER);
$configuration()->setNamingStrategy($namingStrategy);
The linked topic goes on to show you how you can write your own custom naming strategy.
If you're using Symfony, it's even easier (like most things are with Symfony, but that's just my opinion) via config.yml:
doctrine:
orm:
naming_strategy: doctrine.orm.naming_strategy.underscore
Symfony's coding standards encourage Symfony users to use camelCase:
Naming Conventions
Use camelCase, not underscores, for variable,
function and method names, arguments
Personal advice - do not generate entities by doctrine orm:generate-entities.
Use plain PHP to create class. Why?
Orm uses reflection on privates to communicate with database. You dont need to generate setters and getters. I recomend You to use design patterns such as factory or constructor to achive Your goal. Decorators also should work fine.
<?php
class MyClass
{
private $id;
private $name;
public function __construct(int $id, string $name)
{
$this->id = $id;
$this->name = $name;
}
}
$camelCase is not only Symfony's recomendation for code standard. It's based on PSR2. I highly recomend using PSR2, code gets clean and standarized.
Standard ORM naming strategy is $camelCase private var to snake_case column name. If you want to change it otherwise, consider: other naming stategies