GNOME Bugzilla – Bug 316311
parameter documentation after return documentation by using inline comments
Last modified: 2018-07-30 10:34:43 UTC
Please describe the problem: When I use inline comments for parameter and inline comments for return, doxygen write the parameter documentation not in the useful direction function header - parameter - return. Instead of this the output show function header - return - parameter. Using the the comments before the function, the normal output will generated. Steps to reproduce: //! Diese Methode erhoeht den Semaphorenzaehler bis zum Maximalstand. bool Semaphore::release ( unsigned int ncount, //!< Anzahl der Freigaben long *prevcount) //!< Vorheriger Zaehlerstand { return FALSE; //! \return false, wenn die Semaphore nicht freigegeben werden kann //... return TRUE; //! \return true, wenn Funktion erfolgreich ist } Actual results: Wrong direction of the documentation: function header - return - parameter Expected results: function header - parameter - return Does this happen every time? yes Other information:
This bug's version was set to "latest". Since this is a moving target, I changed it to 1.5.3-SVN. If you believe this has already been fixed, then please change the status accordingly.
I've just confirmed that this bug still exists, in Doxygen 1.7.5.1 on Windows. It was just reported on StackOverflow, as question http://stackoverflow.com/q/7800136/104370. And I verified it, in Doxygen 1.7.5.1. See this answer: http://stackoverflow.com/questions/7800136/doxygen-function-paramter-documentation-vs-param/7866750#7866750 I think that this means this should be changed to "Status: CONFIRMED"
Hi Clare, Doxygen doesn't know where in the documentation the user would want the parameters to appear. So to fix this there should be a way to mark the spot in the comment block where doxygen should insert the parameter documentation, or alternatively, there should be a way to apply a certain layout template. So this is in fact an enhancement request.
Even without a way to specify layout, there ought to be a default. By default, doxygen should place parameters, exceptions, and return-value descriptions after the rest of the detailed description, and in the order I just used. I would rather have it behave this way without my having to tell it where to place parameters. Without this, the inline parameter comments are useless, so even if it's an "enhancement" request, it's a pretty serious one. I'm facing the same problem right now.
With respect dkantrowitzpublic I don't think it's a great idea to unconditionally output the param/return value synopsis after the detailed description. The detailed description might run for several pages including example code and whatever. To list the parameter and return value synopsis after all that would be nuts as it would potentially require ther use to have to scroll to the bottom of every definition entry to get to the most commonly useful information. (As an aside it would be nice to have the option for the each member defintion be a link to a separate page linked to from the member declaration list). I think it's pretty obvious how this should work. One thing I think we all agree on is that the documentation for the return value should come _after_ the documentation for the parameters, irrespective of whether the parameters are documented using inline syntax or not. Since the return value documentation is output in the detailed description at the location where the user puts the @return marker then users already have the flexibility to select where they want that to go. So in the case where the parameter documentation is supplied using the inline syntax Doxygen should output it into the detailed description immediately in front of the @return marker. It seems to me that would provide the maximum flexibility for the minimum effort.
As discussed in https://github.com/doxygen/doxygen/pull/734 , Doxygen has moved its issue tracking to https://github.com/doxygen/doxygen/issues All Doxygen tickets in GNOME Bugzilla have been migrated to Github. You can subscribe and participate in the new ticket in Github. You can find the corresponding Github ticket by searching for its Bugzilla ID (number) in Github. Hence I am closing this GNOME Bugzilla ticket. Please use the corresponding ticket in Github instead. Thanks a lot!