Re: [edk2-CCodingStandardsSpecification PATCH 1/1] Function example in Chapter 5 C Programming has extraneous semicolon


Michael D Kinney
 

-----Original Message-----
From: Kinney, Michael D <michael.d.kinney@...>
Sent: Wednesday, December 9, 2020 9:32 AM
To: Rebecca Cran <rebecca@...>; devel@edk2.groups.io; Kinney, Michael D <michael.d.kinney@...>
Cc: Leif Lindholm <leif@...>; Laszlo Ersek <lersek@...>; Andrew Fish <afish@...>
Subject: RE: [edk2-CCodingStandardsSpecification PATCH 1/1] Function example in Chapter 5 C Programming has extraneous
semicolon

Rebecca,

Looks like a BZ was opened for this issue too:

https://bugzilla.tianocore.org/show_bug.cgi?id=1606

Mike

-----Original Message-----
From: Kinney, Michael D <michael.d.kinney@...>
Sent: Wednesday, December 9, 2020 8:41 AM
To: Rebecca Cran <rebecca@...>; devel@edk2.groups.io; Kinney, Michael D <michael.d.kinney@...>
Cc: Leif Lindholm <leif@...>; Laszlo Ersek <lersek@...>; Andrew Fish <afish@...>
Subject: RE: [edk2-CCodingStandardsSpecification PATCH 1/1] Function example in Chapter 5 C Programming has extraneous
semicolon

Hi Rebecca,

Reviewed-by: Michael D Kinney <michael.d.kinney@...>

I see this was a GitHub issue entered in 2019.

We should be using TianoCore Bugzilla to enter specification issues. I appreciate you
noticing this GitHub issue and generating a patch to get this fixed.

There are also recommendations for the Revision History to be updated for each change
with cross links between Revision History, git commit messages, and TianoCore Bugzilla.

https://github.com/tianocore-docs/edk2-TemplateSpecification/wiki/TianoCore-Documents-Editing


There are some examples of this at the end of the Revision History of the EDK II Build Specification.

Ideally, the Revision History contains a link to the TianoCore Bugzilla. A few examples:

| | [#465](https://bugzilla.tianocore.org/show_bug.cgi?id=465) DEC spec: document private definitions
| |

| | [#1110](https://bugzilla.tianocore.org/show_bug.cgi?id=1110) Extend exclamation statement's keyword to
case-insensitive | |
| | [#598](https://bugzilla.tianocore.org/show_bug.cgi?id=598) update supported operators in 8.2.4.6
Expressions | |
| 1.29 | [#1453](https://bugzilla.tianocore.org/show_bug.cgi?id=1453) Update Build spec to remove EDK related
contents | Mar 2019 |
| 1.30 | [#1952](https://bugzilla.tianocore.org/show_bug.cgi?id=1952) Update Build spec to support
HOST_APPLICATION
MODULE_TYPE | July 2019 |

The TianoCore Bugzilla should be updated when the issue is Fixed/Resolved with links to the
GitHub commits for the specification changes.

With this cross linking, when a specification is opened, the reader can review the Revision History,
follow the link to the TianoCore Bugzilla with a discussion of the specification change and see
the links to the final commits. The reader can then follow the links to GitHub commits and see
the text changed rendered with by GitHub with green (add), red (delete), yellow (change) highlight
when the "Display as rich diff" button is selected.

For example, BZ 465

https://bugzilla.tianocore.org/show_bug.cgi?id=465

This BZ contains the full link to the GitHub commits:

https://github.com/tianocore-docs/edk2-BuildSpecification/commit/afb505572de767fa05ca6348d36015faae387df9

If you clink on the "Display as rich diff" button, it will show a more readable version of the change:

https://github.com/tianocore-docs/edk2-
BuildSpecification/commit/afb505572de767fa05ca6348d36015faae387df9?short_path=3d47f51#diff-
3d47f517e576e84d4c7bf02e39d31d597e39821a99fa4fbe08a91f6e03e56961

With the addition of the GitBook Action, you can also create a fork of a document in your personal
GitHub area and provide links to a branch with the proposed document changes that can be viewed
using the "Display as rich diff" for easier/faster community review of document changed. If you
enable the GitBook Action on your personal fork of a document, you can also provide links to the
published versions of the document with the proposed changes.

This full process makes sense for larger changes. Does not seem to make sense for simple typos.

Thanks,

Mike

-----Original Message-----
From: Rebecca Cran <rebecca@...>
Sent: Wednesday, December 9, 2020 7:16 AM
To: devel@edk2.groups.io
Cc: Rebecca Cran <rebecca@...>; Kinney, Michael D <michael.d.kinney@...>; Leif Lindholm
<leif@...>; Laszlo Ersek <lersek@...>; Andrew Fish <afish@...>
Subject: [edk2-CCodingStandardsSpecification PATCH 1/1] Function example in Chapter 5 C Programming has extraneous
semicolon

https://github.com/tianocore-docs/edk2-CCodingStandardsSpecification/issues/1

"Section 5.7.1.10, there is a semicolon after the function paramters.
Probably a copy-paste error from the header file."

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Rebecca Cran <rebecca@...>
---
5_source_files/57_c_programming.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/5_source_files/57_c_programming.md b/5_source_files/57_c_programming.md
index 8b9db584eea7..8b4111bfac29 100644
--- a/5_source_files/57_c_programming.md
+++ b/5_source_files/57_c_programming.md
@@ -102,7 +102,7 @@ FooName (
IN UINTN Arg2, OPTIONAL
OUT UINTN *Arg3,
IN OUT UINTN *Arg4
- );
+ )
{
UINTN Local;
...
--
2.26.2

Join devel@edk2.groups.io to automatically receive all group messages.