gnrc_gomach: add a brief description of GoMacH's features. #8281

zhuoshuguo · 2017-12-19T09:49:28Z

Contribution description

This PR adds a brief description of GoMacH's main features.

Issues/PRs references

See also #5618 .

miri64 · 2017-12-19T10:03:48Z

sys/include/net/gnrc/gomach/gomach.h

 * @ingroup     net_gnrc
- * @brief       A traffic adaptive MAC protocol that provides high traffic
- *              adaptability, high energy efficiency and high robustness.
+ * @brief       GoMacH is, we believe, "a General, nearly Optimal MAC protocol


Do we believie it or know it. Anyway this , we believe, should be removed IMHO.

miri64 · 2017-12-19T10:04:07Z

sys/include/net/gnrc/gomach/gomach.h

- * @brief       A traffic adaptive MAC protocol that provides high traffic
- *              adaptability, high energy efficiency and high robustness.
+ * @brief       GoMacH is, we believe, "a General, nearly Optimal MAC protocol
+ *              for multi-Hop communications", for IEEE 802.15.4 IoT/WSNs networks.


miri64 · 2017-12-19T10:05:22Z

sys/include/net/gnrc/gomach/gomach.h

+ * 3. it adopts duty-cycle scheme to conserve power;
+ * 4. it provides high traffic adaptation for handling burst or dynamic traffics.
+ *    It achieves this by dynamically allocating transmission slots for intensive
+ *    senders (that have pending packets); it enables a (or several) sender


one (or more) sender(s)

miri64 · 2017-12-19T10:05:43Z

sys/include/net/gnrc/gomach/gomach.h

+ *    senders (that have pending packets); it enables a (or several) sender
+ *    to burst transmit all of its buffered packets (for the same destination) to
+ *    the receiver in one shot (or during a shot notice); The burst slotted-transmissions
+ *    (of multi senders) will be ordered by the receiver device in a TDMA period;


multiple senders

miri64 · 2017-12-19T10:06:02Z

sys/include/net/gnrc/gomach/gomach.h

+ *    to burst transmit all of its buffered packets (for the same destination) to
+ *    the receiver in one shot (or during a shot notice); The burst slotted-transmissions
+ *    (of multi senders) will be ordered by the receiver device in a TDMA period;
+ * 5. it adopts multi-channel scheme for avoiding/reducing wireless interference jam.


article missing.

miri64 · 2017-12-19T10:07:27Z

sys/include/net/gnrc/gomach/gomach.h

+ *              high traffic adaptability, high energy efficiency and high robustness.
+ *
+ * ## GoMacH's main features
+ * 1. it is an asynchronous solution which doesn't rely on global synchronization;


I think this whole list can be more paraphrased,

1. doesn't rely on global synchronization 2. support for multi-hop and mesh networks ....

miri64 · 2017-12-19T10:07:59Z

sys/include/net/gnrc/gomach/gomach.h

+ *              high traffic adaptability, high energy efficiency and high robustness.
+ *
+ * ## GoMacH's main features
+ * 1. it is an asynchronous solution which doesn't rely on global synchronization;


Also, why it is an enumerated list? These features do not appear to be in any particular order or priority.

zhuoshuguo · 2017-12-19T10:34:23Z

Addressed comments.

miri64 · 2017-12-19T10:37:08Z

sys/include/net/gnrc/gomach/gomach.h

+ *
+ * ## GoMacH's main features
+ * doesn't rely on global synchronization;
+ * supports for Multi-hop and mesh network;


Why is Multi-hop capitalized now?

Ah, my bad, mistakenly did it. fix soon

miri64 · 2017-12-19T10:37:34Z

sys/include/net/gnrc/gomach/gomach.h

+ *              high traffic adaptability, high energy efficiency and high robustness.
+ *
+ * ## GoMacH's main features
+ * doesn't rely on global synchronization;


Consider removing semi-colons and periods or decide for one of them.

zhuoshuguo · 2017-12-19T10:44:28Z

Addressed comments again~

miri64

Last change request, I promise ^^

miri64 · 2017-12-19T10:57:18Z

sys/include/net/gnrc/gomach/gomach.h

+ *              high traffic adaptability, high energy efficiency and high robustness.
+ *
+ * ## GoMacH's main features
+ * doesn't rely on global synchronization


mh... now it isn't a list anymore I just realized (the stars are just from the C-comment). Probably most readable to do it with dashes:

* - doesn't rely on global synchronization * - ...

zhuoshuguo · 2017-12-19T11:47:12Z

Addressed comments again~

zhuoshuguo · 2017-12-19T11:49:00Z

Will squash after ACK~

smlng · 2017-12-19T13:12:37Z

sys/include/net/gnrc/gomach/gomach.h

 * @ingroup     net_gnrc
- * @brief       A traffic adaptive MAC protocol that provides high traffic
- *              adaptability, high energy efficiency and high robustness.
+ * @brief       GoMacH is, "a General, nearly Optimal MAC protocol


sorry, but this is not brief, maybe the original defgroup description (A traffic-adaptive multi-channel MAC) can be (re) used here. Please note that the @brief sentence will be displayed in doxygen below the group name (GoMacH, here), hence it should be a one-liner. You can use this longer text as as the first paragraph of the detailed description (above the feature list), though.

to make my point a bit clearer, look at the module page in doxygen, the @brief for the boards group is for instance Board specific definitions and implementations.

@zhuoshuguo you can also look at the compiled doc locally by building with make doc in the RIOT root directory. The results will be in doc/doxygen/html/. Choose the module.html to look at the new version of the page @smlng mentioned.

(saw this comment only after ACKing)

miri64

ACK

zhuoshuguo · 2017-12-19T13:45:34Z

sys/include/net/gnrc/gomach/gomach.h

+ * @brief       GoMacH is, "a General, nearly Optimal MAC protocol
+ *              for multi-Hop communications", for IEEE 802.15.4 IoT/WSNs networks.
+ *              It is designed to be a traffic adaptive MAC protocol that provides
+ *              high traffic adaptability, high energy efficiency and high robustness.


@smlng But we have the removed description above texts displayed here~ :-)

Ah, you mean the description should be a one-liner, i.e., not longer than one line (like 2 or 3 lies)? @smlng @miri64

exactly, the text is fine, just add a one-liner for @brief and move these 2 sentences after that (2 empty lines) so its part of the longer description.

Thanks!~ Learned and work on it~ :-)

zhuoshuguo · 2017-12-19T13:58:42Z

Addressed comments and squashed!~

smlng · 2017-12-19T14:03:41Z

compiled docs, looks good!

miri64 requested changes Dec 19, 2017

View reviewed changes

miri64 self-assigned this Dec 19, 2017

miri64 added Area: doc Area: Documentation GNRC CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels Dec 19, 2017

smlng suggested changes Dec 19, 2017

View reviewed changes

miri64 approved these changes Dec 19, 2017

View reviewed changes

zhuoshuguo commented Dec 19, 2017

View reviewed changes

gnrc_gomach: add a brief description of GoMacH's features.

f8b1583

zhuoshuguo force-pushed the gnrc_gomach_add_description branch from 811de4a to f8b1583 Compare December 19, 2017 13:56

smlng approved these changes Dec 19, 2017

View reviewed changes

zhuoshuguo mentioned this pull request Dec 19, 2017

gnrc_lwmac: revise brief description. #8288

Merged

miri64 merged commit 2f78a0c into RIOT-OS:master Dec 19, 2017

aabadie added this to the Release 2018.01 milestone Jan 18, 2018

miri64 added the Area: network Area: Networking label Sep 30, 2018

gnrc_gomach: add a brief description of GoMacH's features. #8281

gnrc_gomach: add a brief description of GoMacH's features. #8281

Uh oh!

Conversation

zhuoshuguo commented Dec 19, 2017

Contribution description

Issues/PRs references

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zhuoshuguo commented Dec 19, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zhuoshuguo commented Dec 19, 2017

Uh oh!

miri64 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zhuoshuguo commented Dec 19, 2017

Uh oh!

zhuoshuguo commented Dec 19, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miri64 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zhuoshuguo commented Dec 19, 2017

Uh oh!

smlng commented Dec 19, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zhuoshuguo Dec 19, 2017 •

edited

Loading