Fix SSP descriptor documentation

[fabiensanglard]

Sorry about the extra =. This was an oversight.

[Youw]

LGTM

[tormodvolden]

I'll copy what I wrote in #1429 (comment), with updated comments:

Doxygen warnings (seen when running make -C doc) caused by this commit:

libusb/descriptor.c:1012: warning: Compound internal_ssplus_capability_descriptor is not documented.
Maybe it needs to be moved? EDIT: Last resort would be masking it with doxygen @cond conditionals. Any other suggestions?

libusb/libusb.h:1077: warning: unable to resolve reference to 'libusb_ssplus_usb_device_capability_descriptor.numSublinkSpeedAttributes=' for \ref command
Caused by the trailing =. What was the intention with those =? EDIT: FIXED

libusb/descriptor.c:1013: warning: Member bLength (variable) of struct internal_ssplus_capability_descriptor is not documented.
libusb/descriptor.c:1014: warning: Member bDescriptorType (variable) of struct internal_ssplus_capability_descriptor is not documented.
libusb/descriptor.c:1015: warning: Member bDevCapabilityType (variable) of struct internal_ssplus_capability_descriptor is not documented.
libusb/descriptor.c:1016: warning: Member bReserved (variable) of struct internal_ssplus_capability_descriptor is not documented.
libusb/descriptor.c:1017: warning: Member bmAttributes (variable) of struct internal_ssplus_capability_descriptor is not documented.
libusb/descriptor.c:1018: warning: Member wFunctionalitySupport (variable) of struct internal_ssplus_capability_descriptor is not documented.
libusb/descriptor.c:1019: warning: Member wReserved (variable) of struct internal_ssplus_capability_descriptor is not documented.

Should they be added? EDIT: Related to first point, probably one solution for all.

libusb/libusb.h:1077: warning: unable to resolve reference to 'libusb_ssplus_usb_device_capability_descriptor.numSublinkSpeedAttributes=' for \ref command

Caused by the trailing = . EDIT: FIXED

[tormodvolden]

Please see the commit I added for the @cond@ alternative. Also any other doxygen fans out there, I would be glad if someone can suggest a prettier way to do it. I know you can prepend \internal to the tag, but then you still need to document all the members.

See also my draft PR #1549 where I investigate adding doxygen validation to the CI.

[fabiensanglard]

Thank you for fixing this :), I am still ramping up on Doxygene !

I'll be more thorough in my next contribution.

[fabiensanglard]

I have added a commit to comment the internal_ssplus_capability_descriptor fields. I tried to run make -C doc but it does not work on my mac. Is it Linux only or am I doing something wrong?

[tormodvolden]

"does not work" does not help me :) Can you please paste the terminal output?

[fabiensanglard]

Sorry, the problem was between the keyboard and the chair. Here are the steps on Macos to build the doc if anybody else reads this.

$ brew install automake
$ brew install libtool
$ brew install doxygen
$ ./autogen.sh
$ ./bootstrap.sh
$ automake
$ ./configure
$ make -C doc
doxygen doxygen.cfg
warning: Tag 'OUTPUT_TEXT_DIRECTION' at line 102 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'HTML_TIMESTAMP' at line 1247 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'FORMULA_TRANSPARENT' at line 1552 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'LATEX_SOURCE_CODE' at line 1865 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'LATEX_TIMESTAMP' at line 1881 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'RTF_SOURCE_CODE' at line 1955 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOCBOOK_PROGRAMLISTING' at line 2060 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'CLASS_DIAGRAMS' at line 2250 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOT_FONTNAME' at line 2292 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOT_FONTSIZE' at line 2299 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOT_TRANSPARENT' at line 2545 of file 'doxygen.cfg' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
/Users/leaf/repos/libusb/libusb/descriptor.c:907: warning: unable to resolve reference to 'libusb_capability_type::LIBUSB_BT_USB_2_0_EXTENSION' for \ref command
/Users/leaf/repos/libusb/libusb/descriptor.c:965: warning: unable to resolve reference to 'libusb_capability_type::LIBUSB_BT_SS_USB_DEVICE_CAPABILITY' for \ref command
/Users/leaf/repos/libusb/libusb/descriptor.c:1133: warning: unable to resolve reference to 'libusb_capability_type::LIBUSB_BT_CONTAINER_ID' for \ref command
/Users/leaf/repos/libusb/libusb/descriptor.c:1193: warning: unable to resolve reference to 'libusb_capability_type::LIBUSB_BT_PLATFORM_DESCRIPTOR' for \ref command
/Users/leaf/repos/libusb/libusb/libusb.h:1097: warning: unable to resolve reference to 'libusb_capability_type::LIBUSB_BT_CONTAINER_ID' for \ref command
/Users/leaf/repos/libusb/libusb/libusb.h:1122: warning: unable to resolve reference to 'libusb_capability_type::LIBUSB_BT_PLATFORM_DESCRIPTOR' for \ref command
/Users/leaf/repos/libusb/libusb/libusb.h:961: warning: unable to resolve reference to 'libusb_capability_type::LIBUSB_BT_SS_USB_DEVICE_CAPABILITY' for \ref command
/Users/leaf/repos/libusb/libusb/libusb.h:935: warning: unable to resolve reference to 'libusb_capability_type::LIBUSB_BT_USB_2_0_EXTENSION' for \ref command

I confirm the warning about ssplus are gone.

[tormodvolden]

Thanks for the fix-ups! I merged this, just amended it to fix some whitespace errors.