[drivers] Update doxygen errors #4111

sg- · 2017-04-04T18:19:11Z

#Updates doxygen errors in documentation for code in the drivers/ directory.

Notes:
Many more commits coming and still some errors with the way we present MBED_DEPRECATED

C:\dev\mbed-os>doxygen doxyfile-developer
warning: doxygen no longer ships with the FreeSans font.
You may want to clear or change DOT_FONTNAME.
Otherwise you run the risk that the wrong font is being used for dot generated graphs.

Status

READY

…ctory.

stop using scope for \addtogroup. It was placing class methods into the group documentation instead of the class documentation. The new style is to explicitly tag the class as @InGroup. This new method will allow the class to be linked in the group page, and the class page will contain the detailed documentation of the class methods.

AnotherButler · 2017-04-04T21:42:00Z

@sg- Thanks for the PR.

Also, we recommend our contributors follow Chris Beam’s seven rules of great commit messages to keep the commit history clear. To match this format, please change your PR title to imperative mood ("Updates" to "Update"), and delete the period at the end. Thanks for your contributions.

0xc0170

Docs !

0xc0170 · 2017-04-05T05:27:36Z

/morph test

mbed-bot · 2017-04-05T07:30:02Z

Result: SUCCESS

Your command has finished executing! Here's what you wrote!

/morph test

Output

mbed Build Number: 1833

All builds and test passed!

sg- · 2017-04-06T16:14:51Z

@geky is there something we can do to make doxygen and MBED_DEPRECATED play nicely together? This can easily be validated in the online IDE by taking a header and generating docs for it in an example program or library

geky · 2017-04-06T19:47:59Z

I'm not sure there's a "trick" we can do in the source code. The MBED_DEPRECATED also has to be compatible with function and template declarations across the three toolchains.

It does look like there's a config option to skip function-like macros:
https://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_skip_function_macros

That should take care of most of the attributes in mbed_toolchain.h. I'm guess it's currently off? Not sure how to change the doxygen config.

If that doesn't work there are other doxygen configuration options for specifying macros during doxygen generation, so we may be able to force the MBED_DEPRECATED to expand to nothing.

pan- · 2017-04-06T21:31:57Z

@geky If ENABLE_PREPROCESSING is set to YES in the doxy file then the macro MBED_DEPRECATED will be expanded to empty spaces (see). It would also requires to have either:

SEARCH_INCLUDES set to yes and INCLUDE_PATH containing the path to mbed_toolchain.h
PREDEFINED containing MBED_DEPRECATED dummy macro replacement for doxygen.

sg- · 2017-04-11T03:32:13Z

@geky @pan- Thanks for the suggestions but they didn't seem to work. To be more clear, the problems is not with the macro definition but its use in the headers. https://github.com/ARMmbed/mbed-os/blob/master/drivers/Ticker.h#L90...L93

Best solution I could come up with has been to remove the extra doxygen comment * to exclude the docs or maybe I misinterpreted your suggestions. Here is what I'm trying to remove

Given this is for our API documentation I kinda like the idea of removing the extra * from private members too and maybe protected. Anything that you wouldn't expect a developer to be using. The private and protected members should still be documented, just not rendered as part of doxygen.

Thoughts?

sg- · 2017-04-11T14:59:12Z

@AnotherButler thanks for the tip. What do you think about 95a5219

geky · 2017-04-11T15:34:53Z

Oh, that works if we just want to remove the documentation. It seems like a reasonable pragmatic approach to me.

sg- · 2017-04-11T17:07:33Z

We still need a DEPRECIATED section of the API guide but this could be hand coded...

pan- · 2017-04-11T18:50:14Z

The private and protected members should still be documented, just not rendered as part of doxygen.

I agree 100%

@geky @pan- Thanks for the suggestions but they didn't seem to work. To be more clear, the problems is not with the macro definition but its use in the headers. https://github.com/ARMmbed/mbed-os/blob/master/drivers/Ticker.h#L90...L93

I guess doxygen is not able to find the correct include and therefore cannot expand the macro.

I obtain the expected result:

With this preprocessor settings:

#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = NO
SEARCH_INCLUDES        = YES
INCLUDE_PATH           = 
INCLUDE_FILE_PATTERNS  = 
PREDEFINED             = "MBED_DEPRECATED_SINCE(f, g)="
EXPAND_AS_DEFINED      = 
SKIP_FUNCTION_MACROS   = NO

Other predefinitions of macros might be required, I didn't run doxygen over the complete mbed tree.

Best way to enable MBED_DEPRICATED APIs to be properly rendered requires using the doxygen preprocessor. This means all device_has labels need to also be defined or the default DOXYGEN_ONLY label applied to the API headers which this commit does. ASYNCH currently exluded.

attach members not using Callback class are not compatible with const and volatile types. This was missed when callback was initially added

AnotherButler · 2017-04-12T20:21:17Z

platform/CircularBuffer.h


 /** Templated Circular buffer class
 *
 *  @Note Synchronization level: Interrupt safe
+ *  @ingroup plaftorm


Please change "plaftorm" to "platform"

sg- · 2017-04-12T20:30:47Z

And this is a test build to track the progress of: https://docs.mbed.com/projects/sam-doxy-test/

All fields are strings, not arrays. Update the PREDEFINED and EXCLUDE_PATTERNS fields.

sg- · 2017-04-19T07:24:41Z

@tommikas Not sure what happened to pr-head here...

tommikas · 2017-04-19T07:27:04Z

The build passed but for some reason the status didn't get updated here. I'll retrigger the job.

theotherjimmy · 2017-04-19T19:29:54Z

@0xc0170 Both @sg- and me have commits on this one, so you have to merge when you feel ready.

adbridge · 2017-04-20T14:55:59Z

/morph test

mbed-bot · 2017-04-20T18:30:59Z

Result: FAILURE

Your command has finished executing! Here's what you wrote!

/morph test

Output

mbed Build Number: 52

Test failed!

bridadan · 2017-04-20T22:24:40Z

/morph test

mbed-bot · 2017-04-20T23:47:15Z

Result: FAILURE

Your command has finished executing! Here's what you wrote!

/morph test

Output

mbed Build Number: 55

Test failed!

bridadan · 2017-04-21T05:48:29Z

/morph test

mbed-bot · 2017-04-21T07:07:16Z

Result: SUCCESS

Your command has finished executing! Here's what you wrote!

/morph test

Output

mbed Build Number: 56

All builds and test passed!

sg- · 2017-04-21T14:29:26Z

Changed release version as this could break existing docs for 5.4 (I think RTOS is still excluded etc.)

adbridge · 2017-04-21T17:00:20Z

ooo that change may have come too late, will check if this has already gone into 5.4.4.
Actually looks like it got changed just in time :)

sg- and others added 2 commits April 4, 2017 12:40

Updates doxygen errors in documentation for code in the drivers/ dire…

b3ce996

…ctory.

0xc0170 approved these changes Apr 5, 2017

View reviewed changes

0xc0170 added the needs: CI label Apr 5, 2017

0xc0170 added ready for merge and removed needs: CI labels Apr 10, 2017

sg- force-pushed the fix-the-docs branch 2 times, most recently from a4d7a89 to 95a5219 Compare April 11, 2017 14:54

sg- added 2 commits April 12, 2017 08:56

Fix typo in doxygen group

cba75f4

sg- force-pushed the fix-the-docs branch from 95a5219 to 6b45278 Compare April 12, 2017 15:28

Add deprecation note to CAN attach

710af8f

attach members not using Callback class are not compatible with const and volatile types. This was missed when callback was initially added

sg- force-pushed the fix-the-docs branch from 6b45278 to 710af8f Compare April 12, 2017 15:31

Disallow doxygen to render protected and private members

9dd24f9

sg- changed the title ~~Updates doxygen errors.~~ [drivers] Updates doxygen errors. Apr 12, 2017

Add configuration file for docs.mbed.com builds

f2cd273

AnotherButler reviewed Apr 12, 2017

View reviewed changes

Fix typo in doxygen tag

61c4d50

doxygen_options update

5f9f8c5

All fields are strings, not arrays. Update the PREDEFINED and EXCLUDE_PATTERNS fields.

sg- force-pushed the fix-the-docs branch from a95f266 to 5f9f8c5 Compare April 18, 2017 02:15

adbridge added needs: CI and removed ready for merge labels Apr 20, 2017

0xc0170 added ready for merge and removed needs: CI labels Apr 21, 2017

adbridge changed the title ~~[drivers] Updates doxygen errors.~~ [drivers] Update doxygen errors Apr 21, 2017

adbridge added release-version: 5.4.4 and removed ready for merge labels Apr 21, 2017

adbridge merged commit 47b1a9e into ARMmbed:master Apr 21, 2017

sg- added release-version: 5.5.0-rc1 and removed release-version: 5.4.4 labels Apr 21, 2017

sg- deleted the fix-the-docs branch April 21, 2017 17:22

[drivers] Update doxygen errors #4111

[drivers] Update doxygen errors #4111

Uh oh!

Conversation

sg- commented Apr 4, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Status

Uh oh!

AnotherButler commented Apr 4, 2017

Uh oh!

0xc0170 left a comment

Choose a reason for hiding this comment

Uh oh!

0xc0170 commented Apr 5, 2017

Uh oh!

mbed-bot commented Apr 5, 2017

Result: SUCCESS

Output

Uh oh!

sg- commented Apr 6, 2017

Uh oh!

geky commented Apr 6, 2017

Uh oh!

pan- commented Apr 6, 2017

Uh oh!

sg- commented Apr 11, 2017

Uh oh!

sg- commented Apr 11, 2017

Uh oh!

geky commented Apr 11, 2017

Uh oh!

sg- commented Apr 11, 2017

Uh oh!

pan- commented Apr 11, 2017

Uh oh!

AnotherButler Apr 12, 2017

Choose a reason for hiding this comment

Uh oh!

theotherjimmy Apr 12, 2017

Choose a reason for hiding this comment

Uh oh!

sg- commented Apr 12, 2017

Uh oh!

sg- commented Apr 19, 2017

Uh oh!

tommikas commented Apr 19, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theotherjimmy commented Apr 19, 2017

Uh oh!

adbridge commented Apr 20, 2017

Uh oh!

mbed-bot commented Apr 20, 2017

Result: FAILURE

Output

Uh oh!

bridadan commented Apr 20, 2017

Uh oh!

mbed-bot commented Apr 20, 2017

Result: FAILURE

Output

Uh oh!

bridadan commented Apr 21, 2017

Uh oh!

mbed-bot commented Apr 21, 2017

Result: SUCCESS

Output

Uh oh!

sg- commented Apr 21, 2017

Uh oh!

adbridge commented Apr 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

sg- commented Apr 4, 2017 •

edited

Loading

tommikas commented Apr 19, 2017 •

edited

Loading

adbridge commented Apr 21, 2017 •

edited

Loading