Fix doxygen for Serial and RawSerial #8413
Conversation
|
/morph build |
Build : SUCCESSBuild number : 3354 Triggering tests/morph test |
Exporter Build : SUCCESSBuild number : 2988 |
Test : SUCCESSBuild number : 3159 |
drivers/Serial.h
Outdated
| */ | ||
| Serial(PinName tx, PinName rx, int baud); | ||
|
|
||
| /* Stream gives us a FileHandle with non-functional poll()/readable()/writable. Pass through |
There was a problem hiding this comment.
Why is this comment being removed? Even you want to get rid of the "should be deprecated note" - which I still think is true - the rest of the comment is meaningful, clarifying that we're specifically bypassing the Stream::readable() that we inherited here because it's broken.
There was a problem hiding this comment.
@kjbracey-arm I reverted the removal as it's not related to the doxygen anyways
| @@ -88,6 +88,7 @@ class RawSerial: public SerialBase, private NonCopyable<RawSerial> { | |||
|
|
|||
| int printf(const char *format, ...); | |||
|
|
|||
| #if !(DOXYGEN_ONLY) | |||
There was a problem hiding this comment.
Protected methods are part of the API, so should really be documented.
These are overrides of the methods in SerialBase, so should be documented there - then if we have inheritance turned on, we don't need further documentation here.
There was a problem hiding this comment.
@kjbracey-arm #8413 (comment)
| @@ -63,10 +63,10 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> { | |||
| * @param tx Transmit pin | |||
| * @param rx Receive pin | |||
| * @param name The name of the stream associated with this serial port (optional) | |||
| * @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE) | |||
| * @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE or 9600) | |||
There was a problem hiding this comment.
How so "or 9600"? I guess you mean platform.default_serial_baud_rate itself defaults to 9600?
There was a problem hiding this comment.
@kjbracey-arm Yeah, MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE is 9600
There was a problem hiding this comment.
@kjbracey-arm I wanted to add the or 9600 because with just a quick glance I don't care about the MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE configuration parameter, I want to know the actual numerical value it defaults to
| @@ -99,13 +95,15 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> { | |||
| return SerialBase::writeable(); | |||
| } | |||
|
|
|||
| #if !(DOXYGEN_ONLY) | |||
There was a problem hiding this comment.
I think _mutex should have been private here, hence excluded that way? And the overridden protected functions should have been already documented in Stream and SerialBase, so picked up by INHERIT_DOCS.
If you're globally trying to exclude protected API methods (despite them being API), then does this trick work? https://stackoverflow.com/questions/11316663/is-it-possible-to-prevent-doxygen-from-outputting-protected-members/11316802
Also, as EXTRACT_ALL is off, aren't these just omitted by being undocumented anyway?
There was a problem hiding this comment.
@AnotherButler Can you help address the doxygen fanciness?
There was a problem hiding this comment.
They are not omitted. Our published site shows the protected member functions.
This PR follows the method we know works. For further Doxygen questions, I suggest contacting @SenRamakri of the core OS team. The doxygen_options.json and doxyfile_options files live in mbed-os, and he typically knows a lot more about them than I do. @c1728p9 also recently put up a PR addressing Doxygen options and may also be able to help.
|
@AnotherButler Can you help clarify which portions of this API I should be hiding in the doxygen and what is the correct way to do so? |
This reverts commit 5ee5b07.
|
As part of our quality push this quarter, we are removing all private and protected member functions (and anything else not public) from the rendered Doxygen on os.mbed.com/docs through the method implemented by @yennster |
Description
This PR fixes the doxygen for Serial and RawSerial, removing protected member functions and attributes and adding clarification
Pull request type