Author Topic: Parsing/formatting of doc comments in function-argument-help  (Read 1821 times)

dmw

  • Senior Community Member
  • Posts: 145
  • Hero Points: 15
Parsing/formatting of doc comments in function-argument-help
« on: August 20, 2010, 05:31:57 pm »
I've noticed some problems with the formatting of doc comments in the pop-up that appears when function-argument-help() is invoked.  Specifically, the handling of \ref seems incorrect.

Here's the comment in code:

       

Here's the pop-up:

       

And here's what doxygen comes up with:

       

Can anything be done in SlickEdit to make this more readable?  Although it would be nice to actually have the \refs translate somehow to links as in the doxygen output, what I really want is for the text to be properly formatted.

ScottW, VP of Dev

  • Senior Community Member
  • Posts: 1471
  • Hero Points: 64
Re: Parsing/formatting of doc comments in function-argument-help
« Reply #1 on: August 23, 2010, 08:36:42 pm »
Can you post the full doc comment for this sample?

Obviously we can't render links without generating the full doc output of your source base. Perhaps we could do something that ties this information to generated doc output if it exists and has been identified to the project.

chrisant

  • Senior Community Member
  • Posts: 1413
  • Hero Points: 131
Re: Parsing/formatting of doc comments in function-argument-help
« Reply #2 on: August 23, 2010, 10:26:49 pm »
The first picture shows the full doc comment for this sample.

I think the issue is no so much that the links don't work, as it is that SE puts all text on lines beginning with \ref into a section at the end.

The \ref is not a full-line categorization notation, it is an inline markup notation.
I.e. it is more similar to or <a>[/url] than it is to <h2></h2> or <li></li>.

I think what dmw was saying is that if SE were even to just ignore and stripp the "\ref {link}" parts then at least the information in the doc comment would still be legible and useful.  As it is, SE not only doesn't generate links, it also garbles and reorganizes the information to the point that the doc comment is no longer readable.

dmw

  • Senior Community Member
  • Posts: 145
  • Hero Points: 15
Re: Parsing/formatting of doc comments in function-argument-help
« Reply #3 on: August 24, 2010, 06:03:55 pm »
Chrisant has restated perfectly the problem I was attempting to illustrate.  There is nothing specific about that particular comment, but nevertheless, here it is:

Code: [Select]
/** \ingroup asyncio     
 * Helper function to populate the setup packet (first 8 bytes of the data
 * buffer) for a control transfer. The wIndex, wValue and wLength values should
 * be given in host-endian byte order.
 *                       
 * \param buffer buffer to output the setup packet into
 * \param bmRequestType see the
 * \ref libusb_control_setup::bmRequestType "bmRequestType" field of
 * \ref libusb_control_setup
 * \param bRequest see the
 * \ref libusb_control_setup::bRequest "bRequest" field of
 * \ref libusb_control_setup
 * \param wValue see the 
 * \ref libusb_control_setup::wValue "wValue" field of
 * \ref libusb_control_setup
 * \param wIndex see the                                                             
 * \ref libusb_control_setup::wIndex "wIndex" field of
 * \ref libusb_control_setup
 * \param wLength see the
 * \ref libusb_control_setup::wLength "wLength" field of
 * \ref libusb_control_setup
 */   
static inline void libusb_fill_control_setup(unsigned char *buffer,
   uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
   uint16_t wLength)
Code from libusb project

Quote
Perhaps we could do something that ties this information to generated doc output if it exists and has been identified to the project.

This would be great!  Consider it a feature request.  But just to be clear, the formatting problem is more important.