Is there a way to have doxygen show the documentation for individual private functions? I want doxygen to not show the documentation for the vast majority of private functions but show it for a select few private functions. My motivation is that these C++ private functions are provided to Python as extensions and I want their documentation to show up in Doxygen. However, I don't want them to be public because they are only needed by the classes themselves; they definitely belong in the private sector.
Thanks
I set the following in the config file:
EXTRACT_PRIVATE = YES
HIDE_UNDOC_MEMBERS = YES
This has the desired effect but will still show the documentation for all documented private members.
I then use #internal as the first line for the documentation of private members that I do not want to show.
Also, I can still document private members with a normal C++ comment. ie. dont use /** ... */ use /* ... */.
Usually I use a normal comment for member variables.
Finally, if I really want to show all that private documentation I can set:
INTERNAL_DOCS = YES
to create a more expansive version of the documentation.
The section between \cond and \endcond commands can be included by adding its section label to the ENABLED_SECTIONS configuration option. If the section label is omitted, the section will be excluded from processing unconditionally.
/** An interface */
class Intf
{
public:
/** A method */
virtual void func() = 0;
/// #cond COND1
/** A method used for testing */
virtual void test() = 0;
/// #endcond
};
See cond help
Not to see COND1 sections: just do not add it to ENABLED_SECTIONS configuration option.
There are a couple of ways to achieve this.
You could simply not document those functions that you don't want visible. By default, Doxygen will not show any members that you did not document. Thus, you can just tell it to show privates and any undocumented private members will not be shown.
Related
Running doxygen for
namespace BV
{
namespace Data
{
typedef struct Station {
uint offsetId; //! The ID of a station is generated by adding an offset to a base (example: 1000)
uint id; //! The ID of the station (see {#link Station.offsetId} for more details)
QString name; //! Name of the station
QStringList lineSwitches; //! A list of available lines the passanger can switch to from the station
} Station;
...
}
}
returns warning
/home/USER/Projects/HelloWorld/src/csvparser.h:16: warning: unable to resolve link to `Station.offsetId' for \link command
Initially I only had offsetId instead of Station.offsetId but after looking online I saw a bunch of examples (including here on SO) that were describing this to be the way. Besides I also want to reference this member in other parts of my header.
Not only do I get the warning from above but I just took a look at the generated HTML documentation for my structure and for my surprise it wasn't even there:
Public Attributes
uint id
The ID of a station is generated by adding an offset to a base (example: 1000)
QString name
The ID of the station (see **Station.offsetId** for more details)
QStringList lineSwitches
Name of the station.
The Station.offsetId is just a broken link.
The documentation as stated in the question uses //! as comment strings, this is intended for usage before the member. When having the documentation after the member one should use //!<. See also "Putting documentation after members" in the doxygen manual.
As a second part it is not necessary to use: {#link Station.offsetId} (actually \link should also have a \endlink. Better is to use \ref or # e.g. \ref Station.offsetId or #offsetId or \ref offsetId or in (this case) just Station.offsetId.
I'm new and getting into programming so I apologize if this has already been answered or explained. Basically, I've been looking in the documentation of the SFML library and come across some sf::Font class public member functions. One for example is this:
bool sf::Font::loadFromFile ( const std::string & filename )
Following that is what the function does:
/// \brief Load the font from a file
///
/// The supported font formats are: TrueType, Type 1, CFF,
/// OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.
/// Note that this function know nothing about the standard
/// fonts installed on the user's system, thus you can't
/// load them directly.
///
/// \warning SFML cannot preload all the font data in this
/// function, so the file has to remain accessible until
/// the sf::Font object loads a new font or is destroyed.
///
/// \param filename Path of the font file to load
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromMemory, loadFromStream
///
I've downloaded the library and looked inside the header files but I can't seem to find how the loadFromFile function actually accomplishes the loading (In other words, I'd be looking for a function body or a function definition that does the work). The documentation only explains what the function does, not how.
I'm sorry if this is a stupid question or something that should be apparent. I'm just extremely curious about where the core of the function is.
By the way, here is an exact link to the page and section of the documentation I'm referring to.
Thank you to anyone who answers.
The method you are looking for can be found in the public Github repository.
It's in the file Font.cpp starting on line 122:
https://github.com/SFML/SFML/blob/master/src/SFML/Graphics/Font.cpp#L122
Documentation will not mention this because the documentation is about the behavior the user of this function can rely on. How a method achieves this behavior is a private implementation detail that the user should not need to know.
I would like to generate a documentation of certain parameters that the Save-Method of various classes in my program generate. For that purpose, I would like to write a comment at the top of my save method, and these comments should go to a html and PDF file.
I would like to use doxygen to parse the source- and header files of my C++ project, however by default, doxygen generates a documentation for all the members and classes in my project, which is not what I actually want.
Is it possible to customize doxygen to generate documentation for only one single method which always has the same signature and Name (int Save();), and nothing else? How can that be achieved?
Have you looked at ENABLED_SECTIONS and the cond command? Here is a snippet of the example:
/// #cond DEV
/*
* The implementation of the interface
*/
class Implementation : public Intf
{
public:
void func();
/// #cond TEST
void test();
/// #endcond
/// #cond
/** This method is obsolete and does
* not show up in the documentation.
*/
void obsolete();
/// #endcond
};
/// #endcond
The output will be different depending on whether or not ENABLED_SECTIONS contains TEST, or DEV.
If this does not help, please clarify your question.
Doxygen is not adding the documentation of any of my member functions in this class:
#ifndef SET_H_
#define SET_H_
/** #file */
/**
* A mathematical set
*/
class Set
{
virtual ~Set();
/**
* The countability of this set
* #returns Whether this set is a countable one or not.
*/
virtual bool isCountable();
...
}
#endif /* SET_H_ */
It produces the class documentation just fine, but not the function documentation even if I set EXTRACT_ALL to YES. Do you know why this is the case?
The function is private unless declared otherwise as public or protected.
By default, doxygen excludes private functions, even when setting EXTRACT_ALL is true. You can include them by adding to the Doxyfile EXTRACT_PRIVATE = YES.
Quoting from Doxygen's FAQ:
Is your class / file / namespace documented? If not, it will not be
extracted from the sources unless EXTRACT_ALL is set to YES in the
config file.
Are the members private? If so, you must set
EXTRACT_PRIVATE to YES to make them appear in the documentation.
Consider I have 2 header files.
// HEADER 1
/**
* Doc for Foo here?
*/
namespace Foo {
class This {...};
}
&&
// HEADER 2
/**
* Doc for Foo here?
*/
namespace Foo {
class That {...};
}
How should I handle this when documenting with Doxygen?
Maybe neither.
For example, imagine you have "<root>/utility/header1.hpp" which has its contents in namespace utility and "<root>/utility/header2.hpp" which does also.
You could add a file: "<root>/utility.hpp" which documents the utility namespace. You could put this at the top #error Documentation only. to make sure it's not accidentally included.
But I would recommend at least making some out-of-the-way file to keep it in a sane place (and not mixed in randomly with some class.)
I have placed documentation for namespaces that span multiple files into another file. My Doxygen builds use a separate file for the #mainpage tag. This forms the root of the built Doxygen, and is also a central location for such namespaces.
So I'll have project_name_mainpage.h, and in that file:
/**
#mainpage title
...whatever you want to tell the user about your application...
*/
/**
* #namespace your_namespace
* #brief An awesome description
* #details More sweet details
*/
Keeps it all in one place, and is relatively easy to find if you need to update it.
Find the best place for the documentation, whether it is in one of those files or another entirely. Use a comment block with Doxygen's namespace tag:
/**
* #namespace Foo
* Documentation for Foo here. More docs for Foo here,
* and down here.
*/
Docs here: http://www.doxygen.nl/manual/commands.html#cmdnamespace