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?
Related
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).
The company I'm working for does not use Doxygen, and in their coding standard explicitly prohibits "parseable comment styles such as javadoc, etc".
However, I've still found it very useful to run Doxygen myself just so I can see the class structure, and get nice per-class documentation of all the methods the a class has, including inherited ones.
The company does document the classes in the header files, with simple comments above each method declaration. It would be very useful if I could configure Doxygen to treat these comments as the function descriptions, even though they don't start with any Doxygen markers.
So: is it possible to get Doxygen to treat comments on the line above declarations as if they are the description for that item even when the comment is not marked with Doxygen's "parse this comment" markers?
The next best thing is to click on the #include <foo.h> links at the top of the class file to jump to the file itself, which I have been using. That doesn't help for seeing all of a derived class's methods in one place, though.
When the comments above the methods have only "normal" comments i.e. with /* or // the best thing to do would be that you write a small filter (see e.g. INPUT_FILTER with sed or awk or ... ) in which you convert (all?) /* / // comments into /** / /// so the comment blocks are parsed by doxygen. The result is not as nice as with "full" doxygen comments.
It is just a workaround and can lead to unexpected results when the INPUT_FILTER does not exclude e.g. // inside strings from consideration.
I'm using Doxygen v1.8.16, on my C# class library. I’d like all of my documented class pages to include text that states what namespace it is part of. I COULD accomplish this manually by adding all the documented class in a namespace to a group using the /ingroup namespaceGroupName command, in the class's comments. But as this seems awfully redundant, time-consuming and error-prone, I’m wondering:
Is there any way to configure the display of a class's namespace, on a class's page (for all classes in all namespaces), without manually editing/listing each class?
Currently, what I'm looking for can only be found on my alphabetical “Class Index” page, where it shows both the class name and the namespace it belongs to, with text as links, in this form: ClassName (Name.Space)
I should mention, I intentionally set the option in my config file: HIDE_SCOPE_NAMES = YES
While changing this option to NO would technically work, it would affect more than just the documented class page, which I don’t want to do. (I would also prefer to have the namespace as a separate text item, like in parenthesis or a different font/size/line.)
Edit: Here is an example of the standard output, and in orange, the change/addition to the output that I'm looking for. (I realize the namespace is displayed in the menu right above the class title, but I need it in the same area as the other groups.)
I have a bunch of namespaces (containing free functions) and classes (containing member functions, obviously), each of which has a Doxygen comment at the top level and some Doxygen comments for its members. They're within a top-level namespace (one for the whole project) and secondary namespaces (to break the project into packages). Like this:
proj/pkg1/foo.hpp: class proj::pkg1::Foo
proj/pkg1/bar.hpp: class proj::pkg1::Bar
proj/pkg1/baz.hpp: namespace proj::pkg1::Baz
proj/pkg2/one.hpp: class proj::pkg2::One
proj/pkg2/two.hpp: namespace proj::pkg2::Two
I don't have any #file comments. They'd be totally redundant, because there's already exactly one main comment per component, which is attached to the main class or namespace.
I tried running this through Doxygen, and the result is a mess:
The namespaces and classes are separated into two different hierarchies, both in the header row and the navigation panel. But I want them all in a single tree, because e.g. pkg2::One belongs alongside pkg2::Two.
The main hierarchy of namespaces is buried three levels down the navigation panel (Project name -> namespaces -> namespace list). It's next to "Namespace Members" - who uses that!?
There's another hierarchy for the files (and directories). This is redundant because these exactly match the hierarchy of namespaces (and classes).
This is digressing a bit now, but I'd also like to add comments to the package namespaces. These have the same problem of separating classes and namespaces (not such a big deal) but also show up various free functions e.g. operator<<(proj::pkg2::One.
Is there any way to clean things up a bit? Maybe with Sphinx and Breathe?
Example screen shot
Here is what Doxygen produces by default on the above code (it doesn't even mention Baz and Two!), and what I prefer it to look like:
This is a particularly horrible hack, but I mention it for the record. You could decide that classes are dealt with best by Doxygen, and relabel all the component namespaces (the third-level ones) to classes. Like this:
namespace proj {
namespace pkg1 {
/// #brief The Doxygen comment goes here.
#ifdef DOXYGEN
class
#else
namespace
#endif
Baz {
Then set PREDEFINED = DOXYGEN in the Doxyfile.
Obviously, the drawbacks to the this are that it looks ugly as sin in the source code, and it's confusing that it shows up as a "class" in the documentation.
To get the ball rolling, here's a possible solution:
Change expectations a bit: instead of hoping for the two level structure to be presented to readers all in one go, put up with part of it presented at a time. Make the user click through a separate page for each namespace in the tree:
The documentation page for the proj namespace shows all the packages it contains (i.e. in the example it shows namespaces pkg1 and pkg2).
Each package namespace page shows all of the classes and component namespaces in it (in separate lists, which is a little annoying, but at least all the stuff for each package is together).
You can hide the tree view with GENERATE_TREEVIEW=NO and hide the header row DISABLE_INDEX=YES.
The mainpage can just be a link to the top-level proj namespace page (with the usual content of the main page moved to the proj detailed description) with code like this:
/**
#mainpage
#ref proj "Click here for the proj documentation"
*/
A slight variation is to manually list the packages in the main page with code like this and bypass the proj namespace page. This would work well for a project that doesn't have an overall top-level namespace, or where you want finer control over the main page.
/**
#mainpage
Packages:
- #ref proj::pkg1 #n #copybrief proj::pkg1
- #ref proj::pkg2 #n #copybrief proj::pkg2
*/
What is the interest of using MarkedObject in itext pdf ?
Show a main use example please. There is only javadoc on the net related to this object.
The MarkedObject class was introduced to allow developers to add attributes to an object when creating XML or HTML. For instance: when you created HTML, you could add an id or class attribute. This use case has disappeared in 2009 when we removed XML and HTML generation from iText.
We thought it could also be used in the context of PDF, more specifically in the context of generating PDF/A. However, we decided to create PDF/A in a difference way, using the IAccessibleElement interface. If you check the API docs, you see that this interface also defines methods to set and get attributes.
In short: you can safely ignore the MarkedObject class: it is no longer used. Writing a "main use example" would be a waste of time.