Doxygen links for a multi-language API - doxygen

We use Doxygen to generate the API and related documentation for our software library. The library is written in C++, exposes a C interface, and includes wrappers for other languages like C# and Python.
Much of the wrapper languages use the same names for structures/classes as the C API. When Doxygen finds one of them it always links to the C structure. I believe I read somewhere this is by design--it links to the first one that was found. How can I get Doxygen to link the one for a particular language? Ideally to also have the generated link only show the structure/class name (ie. not have some prefix).
Very basic example with pseudo-code in case it helps:
C++ pseudo-code:
ConfigurationOptions.h:
/// Data container
struct ConfigurationOptions
{
}
Bar.h:
/// Class to manage ...
class Bar
{
/// Construct object based on specified options.
///
/// \param options
/// A ConfigurationOptions object with ...
Bar(const ConfigurationOptions & options);
}
Python pseudo-code:
ConfigurationOptions.py:
## Data container
class ConfigurationOptions(structure):
def __init__(self):
self.count = 10
Bar.py:
## Class to manage ...
class Bar:
## Construct object based on specified options.
## See ConfigurationOptions documentation.
##
## \param options [ConfigurationOptions]
## A ConfigurationOptions object with ...
def __init__(self, options):
When both files are included in the Doxygen configuration, it will auto-link all references to ConfigurationOptions to the C++ struct ConfigurationOptions. I want the Python documentation to link to the Python objects.
To be clear, using this example, I want the references to ConfigurationOptions in Bar.py (lines 4, 6, 7) to link to the Python ConfigurationOptions, not the C++ one.
I've found a way to do it (at least with Python) by prefixing the element with the name of the Python module (file).
For example:
## \param options [ConfigurationOptions.ConfigurationOptions]
## A ConfigurationOptions.ConfigurationOptions object with ...
But there's downsides to this, and I don't know if it'll work with the other languages.

The problem looks related to the version used, when I use the 1.8.17 version and the current version (1.9.5) I get as class list:
Though when I use the current master version (Doxyfile 1.9.6 (28ec5dc5a74e0b2cbf66ea0fde2696f9c5c340be)) I get:
So it looks to me that there is in the current master a better separation between the python and the C++ part (the python part show though the artificial namespace).
It has to be checked whether or not the links are al correct.
Edit
Regarding the extra problem of the links from python that should link to python I see the following possibilities:
use full qualified names so for ConfigurationOptionsuse ConfigurationOptions.ConfigurationOptions
see to it that the C++ code is embedded into a namespace (maybe conditional just for the documentation (see the doxygen commands like \cond or use preprocessor commands for it).

Related

Is there any difference between the syntax used for TypoScript constants and the syntax for "Extension Configuration"?

For both "TypoScript constants" and "Extension Configuration" (as defined in ext_conf_template.txt) use a common syntax. They are documented here:
Constants (in "TypoScript Template Reference")
Extension Configuration (in "TYPO3 Explained")
An example:
# cat=basic; type=string; label=Some title
title =
Line 1 describes data type, category etc. of the variable.
Alternatively, we might have something like this:
tx_plugins.my_plugin {
# cat=basic; type=string; label=Some title
title =
}
Besides this rather simple example, there are some more things you can do with this.
Where TypoScript constants and Extension Configuration are stored and how they are used is completely different, but I am wondering if we just look at the syntax and the features you can use - is it the same?
e.g.
the available datatypes (boolean, integer etc.)
that you can't use multiline values
that you can use environment variables
how to access files
how to do localization
The reason I ask: To streamline the documentation and also I use this in my own extensions.
Short Answer
The syntax used for TS template constants and extension configuration is the same but there are some minor differences for the available types currently.
Deep Analysis
Extension Configuration
For TYPO3 CMS version 6 the extension manager and configuration was rewriten from scratch based on Extbase and using the FormEngine. Available types are:
int: integer values
int+: positive integer values only
integer: alias for int
color: color picker
wrap: wrap, lines are separated finally by | for the saved value
offset: offset field
options: select
boolean: checkbox
user: user function is used for rendering
small: small text field
string: text field
input: alias for string, only for backwards compatibility, many extensions depend on that
default: alias for string, only for backwards compatibility, many extensions depend on that
Source is available here: https://github.com/TYPO3/TYPO3.CMS/blob/master/typo3/sysext/core/Classes/ViewHelpers/Form/TypoScriptConstantsViewHelper.php#L36
TypoScript Template Constant Editor
On the other hand the TypoScript template constant editor was never rewriten to make use of the FormEngine and has it's own implementation. Here the following types are additionally available:
comment: a checkbox to switch a constant
files: file selection
Source is available here: https://github.com/TYPO3/TYPO3.CMS/blob/master/typo3/sysext/core/Classes/TypoScript/ExtendedTemplateService.php#L993
Other Questions
that you can't use multiline values
That's almost true for the TS constant editor but there is the wrap type to achieve a multiline like functionality. For the extension configuration there are the small and string types.
For the other questions I'm currently not aware of and have to investigate a little bit deeper first:
that you can use environment variables
how to access files
how to do localization
As Typoscript is a configuration it can be used in multiple ways. And TYPO3 uses it differntly. So you have to diferentiate.
Constants can be used only for frontend rendering. there they are a shortcut to use a given value in different places.
Or to easily configure something (extension) without knowledge of detailed setup. Therefore you have the Constant-Editor where you can define constants which got a special information/ comment. It's like the TCA, a help to build forms and automaticaly have some validators for data. as TS-constants only are strings which can be used in the setup you do not have real data types. it is just a configuration to have some validation in the Constant-Editor.
Aside from some recursive replacement (up to a level of 10) of constants in constants definition you have no further options to compute a value.
In Typoscript setup you have (meanwhile) stdWrap funtionality nearly everywhere.
But especially extensions don't evaluate it everywhere. so in some places you have an extension configuration in setup where you only can insert fixed strings. (like in the constants)
on the other hand:
how can an extension be configured (with TYPO3-tools)?
Aside from the Typoscript setup (where you can use the constants), which primarily is used for the frontend rendering (*) you have a global option to configure extensions with the extension manager.
This data is stored serialized in typo3conf/LocalConfiguration.php. since TYPO3 9 unserialized.
It can be accessed in frontend and backend and works globaly, while the frontend typoscript or TSconfig is dependend on the page (and user).
This brings us to the third part of configuration: TSconfig
We have page-TSconfig and user-TSconfig. In pages, be_users and be_groups you can define a configuration with typoscript syntax. This can be enhanced with 'global' PHP code of extensions which inject further configuration in ext_localconf.php and ext_tables.php (or the successors in /Configuration/TCA/ and /Configuration/TCA/Overrides/)
(*) some extensions evaluate the frontend typoscript for configuration of backend modules or plugins-options

Howto generate function index with Doxygen

I'm using Doxygen 1.8.14 (on Gentoo) generating documentation for a large Qt project.
If I set ALPHABETICAL_INDEX to YES (the default), I get a class index - a page with all classes on one page. I have failed to find a setting that generates a page with all functions on one page - I only get a page for each letter.
I stumbled on documentation generated by Doxygen 1.8.4 that seemed to have this, but not for later versions.
Added: If you, in the menu select Classes => Class members => Functions without selecting a letter, you get to the URL "../html/functions_func.html" - which seems right. What happens (in my case) is that functions starting with "a" are listed on functions_func.html instead of all functions. Functions starting with "b" are listed on functions_func_b.html and so on for c, d ... - as expected. functions_func_a.html is just missing.
Looking at the Doxygen Smarty template used, I don't see how this can happen - that functions_func.html doesn't contain all functions, and that functions_func_a.html is missing. This is starting to smell like a bug - but the Smarty code looks right.
Doxygen does not have a feature to generate a function index. Period.
An index for a printed book shows all of the pages on which each indexed word appears. Doxygen provides only an alphabetized function (word) list. But it does not provide for each function (word) a list of places (pages) where that function (word) is used. It turns out that to provide this type of indexing functionality would require technology equivalent to a compiler, which is clearly out of scope for the Doxygen project.

Making ReasonML/Bucklescript output ES5 compatible code

While using ReasonML and Bucklescript, is it possible to configure Bucklescript so it won't generate export statements? I'd prefer if the generated code could be used as is in a browser, that is, being ES5 (or ES6) compatible.
Edit: OK, while trying out the tool chain a bit more, I realize just turning off the export is not enough. See example below:
function foo(x, y) {
return x + y | 0;
}
var Test = /* module */[
/* foo */foo
];
exports.Test = Test;
This code will pollute global namespace if exports is removed, and is simply broken from an ES5 compatibility viewpoint.
Edit 2: Reading on Bucklescript's blog, this seems not possible:
one OCaml module compiled into one JavaScript module (AMDJS, CommonJS, or Google module) without name mangling.
Source.
BuckleScript can output modules in a number of different module formats, which can then be bundled up along with their dependencies using a bundler such as webpack or rollup. The output is not really intended to be used as a stand-alone unit, since you'd be rather limited in what you could do in any case, as the standard and runtime libraries are separate modules. And even something as trivial as multiplication will involve the runtime library.
You can configure BuckleScript to output es6 modules, which can be run directly in the browser as long as your browser supports it. But that would still require manually extracting the standard and runtime libraries from your bs-platform installation.
The module format is configured through the package-specs property in bsconfig.json:
{
...
"packages-specs": ["es6-global"] /* Or "es6" */
}
Having said all that, you actually can turn off exports by putting [###bs.config { no_export }] at the top of the file. But this is undocumented since it's of very limited use in practice, for the above mentioned reasons.

How to get doxygen to use C# naming formats?

My project is in C# and I'm generating some docs using doxygen. I set the INPUT option to point to the directory where all my *.cs source files are. Everything is mostly fine. But when the classes.html index page is generated, some class names (specifically inner classes and enums) appear C++ style. For example:
ClassName::EnumValue
whereas it should be
ClassName.EnumValue
Any way to fix this?

Hiding namespace in method names in a Doxygen doc

I use Doxygen to generate a reference guide for a large C++ API with several namespaces.
The namespace name is added to each variable or method name in the class documentation page. For example for a class such as MyNamespace::MyClass, Doxygen generates a page where each method is documented as follows:
MyNameSpace::MyClass::MyEnum MyNameSpace::MyClass::getSomeType()
I would like to reduce the clutter and have:
MyClass::MyEnum MyClass::getSomeType()
Any hints?