Deprecate MBED_STATIC_ASSERT and MBED_STRUCT_STATIC_ASSERT for built-in keyword

[pea-pod]

Summary of changes

Deprecates (in doxygen only) MBED_STATIC_ASSERT and MBED_STRUCT_STATIC_ASSERT macros as these uses are now provided with the built-in static_assert (or for C without <assert.h>: _Static_assert).

Cuts down the number of MBED_STATIC_ASSERT and MBED_STRUCT_STATIC_ASSERT macro definition #if cases to just C++ or not C++.

If static_assert is not recognized by the compiler, it implies it is before either C11 or C++11. I do not consider this a breaking change as C11 and C++14 are now the minimum supported language versions.

These changes also clean up some of the code documentation as well.

Impact of changes

This should only go in v6.0.0, so no issues assuming at least C11 or C++14 are used.

Migration actions required

Since the MBED_STATIC_ASSERT and MBED_STRUCT_STATIC_ASSERT macros are deprecated, users should use static_assert going forward as these could eventually be removed.

Documentation

Documentation updated in the modified file.

---

Pull request type

[X] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
[] Feature update (New feature / Functionality change / New API)
[] Major update (Breaking change E.g. Return code change / API behaviour change)

---

Test results

[] No Tests required for this change (E.g docs only update)
[X] Covered by existing mbed-os tests (Greentea or Unittest)
[] Tests / results supplied as part of this PR

---

Reviewers

---

[pea-pod]

I want to mention that while I marked the MBED_STRUCT_STATIC_ASSERT as deprecated inside the doxygen comments, I could not figure out a way to accomplish this. I tried:

• Treating the macro as if it were a real function by putting the MBED_DEPRECATED_SINCE macro immediately before it.
• Putting a #warning in the macro expansion but before the "call" to the MBED_STATIC_ASSERT macro (using backslashes).
• Turning the macro itself into a constexpr function so that it could receive the deprecated function attribute (again, using the MBED_DEPRECATED_SINCE macro).

None were successful. I could have easily caused problems with typos and the like, but in any case, if this is something useful and possible, I'll have to be shown the right way to do it.

Finally, fun fact: you can write "struct" in the code comments and it will pass the doxygen spell checker, but you cannot do that with "structs".

[ciarmcom]

@pea-pod, thank you for your changes.
@ARMmbed/mbed-os-core @ARMmbed/mbed-os-maintainers please review.

[kjbracey]

The C++ and C version tests aren't required. Code base is permitted to just assume C++14 and C11.

Plenty of C++14 assumptions in-tree already. Although maybe not C11. But GNU C, ARMC6 and IAR are all set to C11.

[pea-pod]

Ok. I will further simplify this.

[kjbracey]

I want to mention that while I marked the MBED_STRUCT_STATIC_ASSERT as deprecated inside the doxygen comments, I could not figure out a way to accomplish this.

MBED_DEPRECATED_SINCE is for compiler warnings. If you want to mark it in the doxygen comments, you need to put a @deprecated in there. Both would normally be applied, but in a case like this, you'd have to just put the Doxygen in.

Finally, fun fact: you can write "struct" in the code comments and it will pass the doxygen spell checker, but you cannot do that with "structs".

There is a whitelist somewhere in tools you can add words to, if necessary.

[pea-pod]

MBED_DEPRECATED_SINCE is for compiler warnings. If you want to mark it in the doxygen comments, you need to put a @deprecated in there. Both would normally be applied, but in a case like this, you'd have to just put the Doxygen in.

I understand. I did put the Doxygen tag in there for the MBED_STRUCT_STATIC_ASSERT documentation. My main concern was when someone compiles a deprecated function, the compiler emits warnings about its use. This macro would not emit a warning during compilation. In any case, the danger here would be a missing warning message that would only be noticed if someone's code started breaking after whatever release version would remove this.

[kjbracey]

The next question is does the macro even need to exist at all now? Once you've hit C++14/C11, you can assume it's part of the language. No need for the compiler fudging at all.

Obviously there could be some need for fudging for misbehaving compilers (as for anything), but static_assert is one of the easiest new things for a compiler to support, and needs no library backup, so doesn't seem likely that any future fudging will be required.

I've already been using static_assert directly in new code, and not bothering with the macro.

So maybe even mark the base macro deprecated, and strip from codebase? Thoughts @0xc0170 / @evedon / @bulislaw ?

[kjbracey]

I guess MBED_STATIC_ASSERT covers up a C/C++ spelling difference, but <assert.h> defines static_assert as _Static_assert, so you shouldn't have to use _Static_assert in normal code.

(Since C99, C has chosen not to add new non-reserved keywords, so the tokens are all _Sillycase, and headers define sensible-looking names, like <stdbool.h> defining bool as _Bool. I can see the point when it's a new header doing the define, but adding the define to something pre-existing like <assert.h> strikes me as contradictory).

[pea-pod]

Ok. I just updated it to add deprecation messages to both. If this is accepted, I will change the PR title to "Deprecate MBED_STATIC_ASSERT and MBED_STRUCT_STATIC_ASSERT" and clean up the rest of the PR body as necessary.

[kjbracey]

I'd rephrase this to just

Use `static_assert` instead. For C this is provided by `<assert.h>`, and for C++ it is a built-in keyword.

We'd never expect anyone to use _Bool, so no point telling them to use _Static_assert.

[pea-pod]

Done.

[pea-pod]

@kjbracey-arm is this ready to put through CI?

[0xc0170]

CI started

[mbed-ci]

Test run: SUCCESS

Summary: 6 of 6 test jobs passed
Build number : 1
Build artifacts

[kjbracey]

It's just come to my attention that ARM Compiler 6 may be missing its static_assert define from assert.h. It doesn't claim any C11 library support, and apparently that includes this.

This is still fine for me, but I think a follow-up patch that adds

// Cope with ARM Compiler 6 not providing this define
#if !defined __cplusplus && !defined static_assert
#define static_assert _Static_assert
#endif 

would be in order.