New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix doxygen for Serial and RawSerial #8413

Merged
merged 6 commits into from Oct 19, 2018

Conversation

Projects
None yet
7 participants
@yennster
Contributor

yennster commented Oct 12, 2018

Description

This PR fixes the doxygen for Serial and RawSerial, removing protected member functions and attributes and adding clarification

Pull request type

[ ] Fix
[ ] Refactor
[ ] Target update
[ ] Functionality change
[X] Docs update
[ ] Test update
[ ] Breaking change

yennster added some commits Oct 12, 2018

@NirSonnenschein

This comment has been minimized.

Contributor

NirSonnenschein commented Oct 14, 2018

/morph build

@mbed-ci

This comment has been minimized.

mbed-ci commented Oct 14, 2018

Build : SUCCESS

Build number : 3354
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/8413/

Triggering tests

/morph test
/morph export-build
/morph mbed2-build

@mbed-ci

This comment has been minimized.

@mbed-ci

This comment has been minimized.

*/
Serial(PinName tx, PinName rx, int baud);
/* Stream gives us a FileHandle with non-functional poll()/readable()/writable. Pass through

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 15, 2018

Contributor

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.

This comment has been minimized.

@yennster

yennster Oct 15, 2018

Contributor

@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)

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 15, 2018

Contributor

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.

This comment has been minimized.

@yennster
@@ -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)

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 15, 2018

Contributor

How so "or 9600"? I guess you mean platform.default_serial_baud_rate itself defaults to 9600?

This comment has been minimized.

@yennster

yennster Oct 15, 2018

Contributor

@kjbracey-arm Yeah, MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE is 9600

This comment has been minimized.

@yennster

yennster Oct 15, 2018

Contributor

@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)

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 15, 2018

Contributor

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?

This comment has been minimized.

@yennster

yennster Oct 15, 2018

Contributor

@AnotherButler Can you help address the doxygen fanciness?

This comment has been minimized.

@AnotherButler

AnotherButler Oct 16, 2018

Contributor

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.

@yennster

This comment has been minimized.

Contributor

yennster commented Oct 15, 2018

@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?

@AnotherButler

This comment has been minimized.

Contributor

AnotherButler commented Oct 15, 2018

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

@cmonr cmonr referenced this pull request Oct 19, 2018

Merged

Rollup PR #8475

@cmonr cmonr removed the rollup PR label Oct 19, 2018

@cmonr cmonr merged commit 383798b into ARMmbed:master Oct 19, 2018

11 checks passed

continuous-integration/jenkins/pr-head This commit looks good
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
jenkins-ci/cloud-client-test Success
Details
jenkins-ci/unittests Success
Details
travis-ci/astyle Passed, 666 files (+0 files)
Details
travis-ci/docs Local docs testing has passed
Details
travis-ci/events Passed, runtime is 9236 cycles (+96 cycles)
Details
travis-ci/gitattributestest Local gitattributestest testing has passed
Details
travis-ci/licence_check Local licence_check testing has passed
Details
travis-ci/littlefs Passed, code size is 8372B (+0.00%)
Details
travis-ci/tools-py2.7 Local tools-py2.7 testing has passed
Details

@cmonr cmonr removed the needs: CI label Oct 19, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment