I have a template class that has a bunch of pure virtual and implemented virtual functions. I then have children inherit from this class. I want to document the functions in the virtual parent class and have children inherit this documentation in Doxygen.
For example (I can't post the real source).
template <typename A>
class Parent {
/** Documentation
*/
virtual void pure() = 0;
/** More Docs
*/
virtual void notpure() {
...
}
};
In a different file with all proper includes (at least for the compiler)
class Child: public Parent<int> {
void pure() {
...
}
};
I then want Doxygen to generate documentation for both classes with the same documentation for each function unless I re-document the overridden function.
I run Ubuntu 14.04 and use the repository Doxygen 1.8.6 in case it matters.
Thank you
So, I will answer my own question. Sort of.
If anyone has this same problem, be sure to check for comment bugs. Doxygen handled my templates fine, but I did have a problem because I have the habit of putting /* code /**/ in my programs so I can quickly uncomment large blocks of code quickly while debugging. Doxygen does not like this!.
I had the error message
File ended in the middle of a comment block! Perhaps a missing \endcode?
It took me a while to wade through the warnings generated because I had several undocumented files. This was taken care of by using
EXTRACT_ALL = YES
In my config file. HERE is someone who has a similar problem as I was.
According to the INHERIT_DOCS tag, it should already do that if you have it set to 'yes'.
AFAIK doxygen has had some problems with parsing templates classes and that might be the reason why your documentation isn't being duplicated (i.e. doxygen thinks Child inherits from a different Parent class).
You might try to force this behavior by using the \copydoc command. If that still doesn't work you might have to either ask for a patch or fix it yourself.
I've had a similar problem generating docs of an abstract class. The solution was to make the methods public (by default in a C++ class all methods are private and you need to set EXTRACT_PRIVATE to YES in your Doxygen config file for docs be generated).
I hope this helps someone!
Related
I’m trying to create a custom audio sink plugin for gstreamer using the Gst::AudioSink as a base class. For me this involves multiple learning curves as I’m new to gstreamer, gstreamermm and gobject. Also I have no background or real interest in gtkmm as I’m not working on GUI code at present.
I am trying to create a class along the lines of:
class MyAudioSink: public Gst::AudioSink
{
public:
explicit MyAudioSink(MyAudioSink *gobj);
virtual ~MyAudioSink();
static void class_init(Gst::ElementClass<MyAudioSink> *klass);
virtual int write_vfunc(gpointer data, guint length) override;
virtual void reset_vfunc();
};
I seem to missing some magic in the class_init() function that should link the base class functions to the virtual functions in MyAudioSink.
In C we would do something like:
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
GstAudioSinkClass *audio_sink_class = GST_AUDIO_SINK_CLASS (klass);
audio_sink_class->write = GST_DEBUG_FUNCPTR (myaudiosink_write);
I don’t really grok the C++ binding to gobject.
What is the equivalent for linking to the C++ virtual function hierarchy?
I got the impression from Marcin’s video https://gstconf.ubicast.tv/videos/gstreamermm-c-way-of-doing-gstreamer-based-applications/ that the virtual functions should be invoked automatically.
I can create a half usable (doesn’t handle things like EOS) plugin by adding:
add_pad(sinkpad = Gst::Pad::create(get_pad_template("sink"), "sink"));
sinkpad->set_chain_function(sigc::mem_fun(*this, &MyAudioSink::chain));
But I don't think a sink should have a chain function.
I've also asked this question on the gtkmm mailing list. If I get an answer there I will post it here.
For MyAudioSink I get a class hierarchy of:
GObject +----GInitiallyUnowned
+----GstObject
+----GstElement
+----myaudiosink
Rather than:
GObject +----GInitiallyUnowned
+----GstObject
+----GstElement
+----GstBaseAudioSink
+----GstAudioSink
+----myaudiosink
I suspect this is the essence of my problem.
For the audiofilter example Marcin mentions here I get a class hierachy of:
GObject +----GInitiallyUnowned
+----GstObject
+----GstElement
+----GstBaseTransform
+----GstAudioFilter
+----myaudiofilter
You can find examples of writing your own plugin in the repository: https://git.gnome.org/browse/gstreamermm/tree/tests/plugins/derivedfrombasetransform.h
In general, your header looks ok, and full implementation should look (more or less) like that:
class MyAudioSink: public Gst::AudioSink
{
public:
explicit MyAudioSink(KantarAudioSink *gobj)
: Glib::ObjectBase(typeid (MyAudioSink)),
Gst::AudioSink(gobj) {}
static void class_init(Gst::ElementClass<MyAudioSink> *klass)
{
// Y
klass->set_metadata("longname", "classification", "description", "author");
klass->add_pad_template(Gst::PadTemplate::create("sink", Gst::PAD_SINK, Gst::PAD_ALWAYS, Gst::Caps::create_any()));
}
virtual int write_vfunc(gpointer data, guint length) override {}
virtual void reset_vfunc() {}
};
Very recently we had a bug report when someone posted very nice, tiny example of audiofilter plugin, you can use it as an example for your project as well: https://bug794249.bugzilla-attachments.gnome.org/attachment.cgi?id=369564
If this doesn't work, feel free to file a bug here: https://bugzilla.gnome.org/enter_bug.cgi?product=gstreamermm
It turns out that much of my troubles were caused by cutting and pasting
this into MyAudioSink class:
static GType get_base_type()
{
return Element::get_base_type();
}
This had the effect of telling gobject that my class is based on gstElement which was wrong.
I thought it was some innocent cast like incantation.
This shows the perils of cut and paste but more than that the perils of coding blindly.
I was also guilty of oversimplifying the sample code I pasted here such that no-one my question doesn't show the problem.
That fixes my problem but does not answer my question.
I will try to summarise that below.
"What is the equivalent for linking to the C++ virtual function hierarchy?"
To create a wrapper to a gobject class the normal process is to use glibmmproc.
The wrapper is defined by files with extension .hg and .ccg from which the C++ interface and a gobject wrapper are generated.
For example to wrap a gobject classs foo you might create Foo.hg and Foo.ccg.
glibmmproc would then generate Foo.h and Foo.cc.
Foo.cc includes most of your definition of the Foo class but with
an additional gobject wrapper Foo_class.
Foo_class is a gobject class which wraps gobject virtual functions (vfunc_callbacks) and forwards them to Foo
allowing derived classes of Foo to use C++ inheritance and C++ virtual functions.
The boilerplate is hidden and a C++ developer need for the most part only worry about the C++ interface provided by Foo.h
One way to understand the internals is to build gstreamermm from source and study the code generated by glibmmproc.
For my case this would be: gstreamermm/audiosink.cc & gstreamermm/audiosink.h generated from
src/audiosink.ccg and src/audiosink.hg
So how does the derived C++ class register itself?
Gst::ElementFactory::register_element() - registers the class with gstreamer
Gst::register_mm_type - records the inheritance relationship
See your local /usr/include/gstreamermm-1.0/gstreamermm/register.h for the implementation
Glib::ObjectBase(typeid (MyAudioSink)) is not required in my case as I am not using multiple inheritance. However it is critical in other applications which do. See for example Implementing a custom gtkmm treemodel
I'm trying to get Doxygen to ignore an inheritance relationship when drawing collaboration diagrams.
Let's say my class definition looks like this:
class Derived : public Base
{
int x;
int y;
int z;
}
Now, when I run Doxygen, I don't want to see Base class in the generated collaboration diagram.
At first glance, it seems that the cleanest way to do this would be to use the EXCLUDE_SYMBOLS directive in my Doxyfile. Specifically:
EXCLUDE_SYMBOLS = Base
However, I've found that this does not work: The Base class still shows up in my collaboration diagram for Derived. I've tried this on both Doxygen 1.8.6 and 1.8.11 and with different permutations of Base wildcards (Base*, *as*, etc), same behavior. The Base class always shows up in my collaboration diagram.
To be fair, I have found 2 workarounds, but they both involve putting conditional statements into my code. For completeness, I'll include both here:
First Workaround Method:
class Derived :
#ifndef DOXYGEN_SHOULD_SKIP_THIS
public Base
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
{
...
}
Then ensure that the following two directives are set inside the Doxyfile:
PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
ENABLE_PREPROCESSING = YES
Second Workaround Method:
class Derived :
/// #cond DOXYGEN_IGNORE
public Base
/// #endcond
{
...
}
To be clear, these workarounds do indeed make Doxygen ignore the inheritance relationship, but I'd prefer not to unnecessarily pollute my code base, especially if there's a better / cleaner way to accomplish my goal.
My question is -- Why doesn't EXCLUDE_SYMBOLS make Doxygen ignore my Base class when it draws the collaboration diagram?
If i am not mistaken, EXCLUDE_SYMBOLS prevents Doxygen from generating documentation for the excluded symbols, but it does not hide them. This means Doxygen won't generate documentation for your Base class, but it will still mention it as the base class of Derived, just like if Derived inherited from a class provided by an external library, the name of the class provided by the library would appear in the collaboration diagram.
Is it possible to hide C++ private field/methods from autocomplete popup on QtCreator?
Although I saw the bug report for QtCreator 2.0, Does the same problem still exist on QtCreator3.0? Is there any workaround for this problem? Any help would be apprecated. Thanks in advance.
[Example code]
// SomeClass.h
class SomeClass{
public:
void methodA();
private:
int fieldB;
void methodB();
}
//main.cpp
int main()
{
SomeClass obj;
______________
obj.|fieldB | <- Popup window appears when '.' key is entered.
|methodA() | // I want to hide private fieldB and methodB from the popup
|methodB() | // if possible.
|_____________|
return 0;
}
take a look at http://en.wikipedia.org/wiki/Opaque_pointer#C.2B.2B
Its just so you have the 'private member pointer' to a struct/class that defines all that should be hidden from the user of your class. and it is one member that is really private, the rest should then be public or inherited.
and it was designed to reduce compile time with the side effect of having a clear interface. also Qt uses it a lot via d-ptr pattern. http://qt-project.org/wiki/Dpointer
cheers
There is definitely no such functionality in qt creator as of now. As bug report comments point out, it might get rather difficult to tell what is accessible from where - mostly because friend classes/functions, inheritance and protected, templates. Qt creator would really have to include fully standard-compliant parser, which would probably be way too much - latest creator starts to work rather sluggish on more complex projects for me already.
You can't. And hey, there is no need for that!
Probably "since the begining of the history" developers use simplest trick one can imagine. They choose specific prefix for all private fields. Some choose m_ but i'd rather recommend you using simply _ since it's least probable someone starts a name of "normal" function with. So adjust your definition of class to
class SomeClass{
public:
void methodA();
private:
int _fieldB;
void _methodB();
}
Oh, and also QtCreator is smart: all matching symbols will be at the bottom of the list. Enjoy!
Is there some tool to generate class hierarchy/dependency diagrams by inspecting C++ code in Linux?
I have this big collection of C++ files given to me and such a tool would be invaluable to help me
understand the source code. I am getting a little tangled up in understanding it.
Try doxygen. It may also be shipped with your distribution.
You may need GraphViz to generate the graphs. There is a simple example and output.
And this is a more complicated example from the legend file generated by doxygen:
Code (NOTE: if you only want to generate the graphs, the comments are not required.):
/*! Invisible class because of truncation */
class Invisible { };
/*! Truncated class, inheritance relation is hidden */
class Truncated : public Invisible { };
/* Class not documented with doxygen comments */
class Undocumented { };
/*! Class that is inherited using public inheritance */
class PublicBase : public Truncated { };
/*! A template class */
template<class T> class Templ { };
/*! Class that is inherited using protected inheritance */
class ProtectedBase { };
/*! Class that is inherited using private inheritance */
class PrivateBase { };
/*! Class that is used by the Inherited class */
class Used { };
/*! Super class that inherits a number of other classes */
class Inherited : public PublicBase,
protected ProtectedBase,
private PrivateBase,
public Undocumented,
public Templ<int>
{
private:
Used *m_usedClass;
};
Result:
You do not need to comment your code to generate these graphs. The first example has no comments at all. The second example has one class without doxygen style comment. Just set the appropriate parameter (at least EXTRACT_ALL = YES should be set. I cannot recall whether this is all that is needed).
There's a promising new tool called cpp-depenencies.
It can generate component dependency diagrams (like below) as well as class hierarchy diagrams (by passing an option to treat each source file as a component).
There's also cpp_dependency_graph, which is able to generate component/include dependency graphs in dot, d3.js or JSON formats.
Below is an example d3.js visualisation.
Disclaimer - I am the author of cpp_dependency_graph.
If you use Eclipse as IDE, you can use type hierarchy to see class hierarchy.
If you use kdevelop, you could install kdevcontrolflowgraphview plugin.
Source Trail is an easy-to-use tool in my experience with an intuitive GUI that helps you explore the relationship between a language element and others that are related to it. It worked very well for me on MacOS.
As of September 2021, it is no longer developed, but the repository remains available.
I came across this problem via a colleague today. He had a design for a front end system which goes like this:
class LWindow
{
//Interface for common methods to Windows
};
class LListBox : public LWindow
{
//Do not override methods in LWindow.
//Interface for List specific stuff
}
class LComboBox : public LWindow{} //So on
The Window system should work on multiple platforms. Suppose for the moment we target Windows and Linux. For Windows we have an implementation for the interface in LWindow. And we have multiple implementations for all the LListBoxes, LComboBoxes, etc. My reaction was to pass an LWindow*(Implementation object) to the base LWindow class so it can do this:
void LWindow::Move(int x, int y)
{
p_Impl->Move(x, y); //Impl is an LWindow*
}
And, do the same thing for implementation of LListBox and so on
The solution originally given was much different. It boiled down to this:
#define WindowsCommonImpl {//Set of overrides for LWindow methods}
class WinListBox : public LListBox
{
WindowsCommonImpl //The overrides for methods in LWindow will get pasted here.
//LListBox overrides
}
//So on
Now, having read all about macros being evil and good design practices, I immediately was against this scheme. After all, it is code duplication in disguise. But I couldn't convince my colleague of that. And I was surprised that that was the case. So, I pose this question to you. What are the possible problems of the latter method? I'd like practical answers please. I need to convince someone who is very practical (and used to doing this sort of stuff. He mentioned that there's lots of macros in MFC!) that this is bad (and myself). Not teach him aesthetics. Further, is there anything wrong with what I proposed? If so, how do I improve it? Thanks.
EDIT: Please give me some reasons so I can feel good about myself supporting oop :(
Going for bounty. Please ask if you need any clarifications. I want to know arguments for and vs OOP against the macro :)
Your colleague is probably thinking of the MFC message map macros; these are used in important-looking places in every MFC derived class, so I can see where your colleague is coming from. However these are not for implementing interfaces, but rather for details with interacting with the rest of the Windows OS.
Specifically, these macros implement part of Windows' message pump system, where "messages" representing requests for MFC classes to do stuff gets directed to the correct handler functions (e.g. mapping the messages to the handlers). If you have access to visual studio, you'll see that these macros wrap the message map entries in a somewhat-complicated array of structs (that the calling OS code knows how to read), and provide functions to access this map.
As MFC users, the macro system makes this look clean to us. But this works mostly because underlying Windows API is well-specified and won't change much, and most of the macro code is generated by the IDE to avoid typos. If you need to implement something that involves messy declarations then macros might make sense, but so far this doesn't seem to be the case.
Practical concerns that your colleague may be interested in:
duplicated macro calls. Looks like you're going to need to copy the line "WindowsCommonImpl" into each class declaration - assuming the macro expands to some inline functions. If they're only declarations and the implementations go in a separate macro, you'll need to do this in every .cpp file too - and change the class name passed into the macro every time.
longer recompile time. For your solution, if you change something in the LWindow implementation, you probably only need to recompile LWindow.cpp. If you change something in the macro, everything that includes the macro header file needs to be recompiled, which is probably your whole project.
harder to debug. If the error has to do with the logic within the macro, the debugger will probably break to the caller, where you don't see the error right away. You may not even think to check the macro definition because you thought you knew exactly what it did.
So basically your LWindow solution is a better solution, to minimize headaches down the road.
Does'nt answer your question directly may be, but can't help from telling you to Read up on the Bridge Design pattern in GOF. It's meant exactly for that.
Decouple an abstraction from its
implementation so that the two can
vary independently.
From what I can understand, you are already on the right path, other than the MACRO stuff.
My reaction was to pass an
LWindow*(Implementation object) to the
base LWindow class so it can do this:
LListBox and LComboBox should receive an instance of WindowsCommonImpl.
In the first solution, inheritance is used so that LListBox and LComboBox can use some common methods. However, inheritance is not meant for this.
I would agree with you. Solution with WindowsCommonImpl macro is really bad. It is error-prone, hard to extend and very hard to debug. MFC is a good example of how you should not design your windows library. If it looks like MFC, you are really on a wrong way.
So, your solution obviously better than macro-based one. Anyway, I wouldn't agree it is good enough. The most significant drawback to me is that you mix interface and implementation. Most practical value of separating interface and implementation is ability to easily write mock objects for testing purposes.
Anyway, it seems the problem you are trying to solve is how to combine interface inheritance with implementation inheritance in C++. I would suggest using template class for window implementation.
// Window interface
class LWindow
{
};
// ListBox interface (inherits Window interface)
class LListBox : public LWindow
{
};
// Window implementation template
template<class Interface>
class WindowImpl : public Interface
{
};
// Window implementation
typedef WindowImpl<LWindow> Window;
// ListBox implementation
// (inherits both Window implementation and Window interface)
class ListBox : public WindowImpl<LListBox>
{
};
As I remember WTL windows library is based on the similar pattern of combining interfaces and implementations. I hope it helps.
Oh man this is confusing.
OK, so L*** is a hierarchy of interfaces, that's fine. Now what are you using the p_Impl for, if you have an interface, why would you include implementation in it?
The macro stuff is of course ugly, plus it's usually impossible to do. The whole point is that you will have different implementations, if you don't, then why create several classes in the first place?
OP seems confused. Here' what to do, it is very complex but it works.
Rule 1: Design the abstractions. If you have an "is-A" relation you must use public virtual inheritance.
struct Window { .. };
struct ListBox : virtual Window { .. };
Rule 2: Make implementations, if you're implementing an abstraction you must use virtual inheritance. You are free to use inheritance to save on duplication.
class WindowImpl : virtual Window { .. };
class BasicListBoxImpl : virtual ListBox, public WindowImpl { .. };
class FancyListBoxImpl : public BasicListBoxImpl { };
Therefore you should read "virtual" to mean "isa" and other inheritance is just saving on rewriting methods.
Rule3: Try to make sure there is only one useful function in a concrete type: the constructor. This is sometimes hard, you may need some default and some set methods to fiddle things. Once the object is set up cast away the implementation. Ideally you'd do this on construction:
ListBox *p = new FancyListBoxImpl (.....);
Notes: you are not going to call any abstract methods directly on or in an implementation so private inheritance of abstract base is just fine. Your task is exclusively to define these methods, not to use them: that's for the clients of the abstractions only. Implementations of virtual methods from the bases also might just as well be private for the same reason. Inheritance for reuse will probably be public since you might want to use these methods in the derived class or from outside of it after construction to configure your object before casting away the implementation details.
Rule 4: There is a standard implementation for many abstractions, known as delegation which is one you were talking about:
struct Abstract { virtual void method()=0; };
struct AbstractImpl_Delegate: virtual Abstract {
Abstract *p;
AbstractImpl_Delegate (Abstract *q) : p(q) {}
void method () { p->method(); }
};
This is a cute implementation since it doesn't require you to know anything about the abstraction or how to implement it... :)
I found that
Using
the preprocessor #define directive to
define constants is not as precise.
[src]
Macros are apparently not as precise, I did not even know that...
The classic hidden dangers of the preprocessor like:
#define PI_PLUS_ONE (3.14 + 1)`
By doing so, you avoid the possibility
that an order of operations issue will
destroy the meaning of your constant:
x = PI_PLUS_ONE * 5;`
Without
parentheses, the above would be
converted to
x = 3.14 + 1 * 5;
[src]