GNOME Bugzilla – Bug 378810
Extra signals documentation not used
Last modified: 2007-04-16 16:28:27 UTC
Since we made gmmproc automatically add a Doxygen comment block with the signal handler's signature, Doxygen no longer uses any comment block that we added manually. We get, for instance: /** The delete_event signal is emitted if a user requests that * a toplevel window is closed. The default handler for this signal * hides the window. * * @param event the event which triggered this signal. * @result true to stop other handlers from being invoked for the event, * or false to propagate the event. further. */ /** @par Prototype: * <tt>bool %delete_event(GdkEventAny* event)</tt> */ Glib::SignalProxy1< bool,GdkEventAny* > signal_delete_event(); Unless they are all in one /** * **/ block, only the second set of text is used.
Created attachment 86177 [details] [review] Proposed patch This patch does basically the following: First, it adds '/**' as a separate token that is handled different to '/*'. When the closing '*/' of a '/**' comment is encountered, it checks whether a _WRAP_SIGNAL follows. If so, it does not close the comment but calls on_wrap_signal on its own with a new boolean parameter that says that there was already a previous command. The Outputter eventually gets that parameter. If it is set, then it strips away the leading '/**' from the refdoc comment to merge it with the already-encountered manual comment.
Excellent, even if it makes gmmproc even more of a big (necessary) hack. I wonder if it's too specific to _WRAP_SIGNAL, but we can reuse this for other stuff in future if necessary. Please apply to svn trunk.
I was surprised by the mention of 3 spaces indentation. Please try to make sure that indentation is eventually multiples of 2 spaces.
There was 3 spaces indentation instead of 2 spaces because the continuing comment uses 2 spaces normal indentation and 1 space extra indentation because of the '/' of the '/*' in a comment like /** Foobar * Baz. */ I fixed this by quoting the doxygen comment in SVN (so that m4 does not strip away leading whitespace). This way, gmmproc can insert the required indentation.
Committed to glibmm-2-8, glibmm-2-10, glibmm-2-12, and trunk.