Skip to content

driver/ata8520e: minor doc fixes#8449

Merged
aabadie merged 1 commit intoRIOT-OS:masterfrom
haukepetersen:opt_driver_ata8520e-doc
Jan 30, 2018
Merged

driver/ata8520e: minor doc fixes#8449
aabadie merged 1 commit intoRIOT-OS:masterfrom
haukepetersen:opt_driver_ata8520e-doc

Conversation

@haukepetersen
Copy link
Copy Markdown
Contributor

Contribution description

Just minor doc fixes, should be quite straight forward:

  • some doxygen blocks were not aligned to 4 spaces (this upset my text editor :-) )
  • added missing information about return buffer sizes for some read functions

Issues/PRs references

#7087

@haukepetersen haukepetersen added Area: doc Area: Documentation Impact: minor The PR is small in size and might only require a quick look of a knowledgeable reviewer Area: drivers Area: Device drivers CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels Jan 26, 2018
Copy link
Copy Markdown
Contributor

@aabadie aabadie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor changes, only doxygen.

ACK

*
* @param[in] dev Pointer to device descriptor
* @param[out] pac String containing the pac
* @param[out] pac String containing the pac, must be able to hold 8
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oups, ACK'ed to fast, this is not 8, but 16 here

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ups, I misread the code, just saw the SIGFOX_PAC_LENGTH >> 1 but didn't notice that it was the parameter for fmt_bytes_hex() and not for transfer_bytes... Will fix.

Copy link
Copy Markdown
Contributor Author

@haukepetersen haukepetersen Jan 26, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but wait, wouldn't it meant that the resulting string size is 17 then? The _read_pac() function copies 16 characters into the result string and then puts the \0 byte in the 17th position (array offset 16) of the result string, right?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right, I spoke too fast. That's what the driver test application does: see here

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perfect, then I will adapt this to the really correct numbers :-)

* @param[in] dev Pointer to device descriptor
* @param[out] pac String containing the pac
* @param[in] dev Pointer to device descriptor
* @param[out] pac String containing the pac, must be able to hold 8
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@haukepetersen haukepetersen force-pushed the opt_driver_ata8520e-doc branch from 7932b60 to 8a025a5 Compare January 26, 2018 12:53
@haukepetersen
Copy link
Copy Markdown
Contributor Author

adapted the required buffer sizes for read_pac and read_id (already squashed accidentally...)

Copy link
Copy Markdown
Contributor

@aabadie aabadie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nit

ATA8520E_ATMEL_OPENING_ERROR, /**< Opening error */
ATA8520E_ATMEL_CLOSING_ERROR, /**< Closing error */
ATA8520E_ATMEL_SEND_ERROR /**< Send error */
ATA8520E_ATMEL_OK, /**< No error */
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert the doxygen 1 character shift of this enum, it seems unrelated.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no, it is not, see the first commit of this PR: acac429

Alignment in the master was off for one space for this block...

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alignment in the master was off for one space for this block...

I don't understand. Are you still talking of the "multiple of 4" indentations requirements? I don't consider this as a rule of thumb for alignment, thus the doxygen comment alignment is not 'off' in master. Maybe you should update your editor configuration ?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm refering this comment: "some doxygen blocks were not aligned to 4 spaces (this upset my text editor :-) )"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I am still talking about the 4-space alignment. In master, the this doxygen block is indented by 45 characters and 45 % 4 != 0. So I put moved it to 44 characters -> now 4-space aligned.

I don't consider this as a rule of thumb for alignment

But the coding convention does per default, as long as there is no good reason not to do so. I always interpreted this also applicable to doxygen blocks -> so yes, I say the 4-space alignment does apply here.

Furthermore, even if ignoring the 4-space alignment rule, it does not make sense to indent the block in questions here in a different style than the two blocks below...

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@haukepetersen what about stopping discussing what I'm requested and revert this change ? Those doxygen comments are aligned on their own and the code is nice enough (and not only because I wrote it ;) ).

The only meaningful change of this PR is related to the documentation of payload sizes that are incorrect. Only this should be changed I think.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is completely valid to piggy-back these kind of formatting fixes (and in this case it is a fix) with a related PR if the change in question is kept in its own commit. This is the case here, so let's not block this PR on a matter of opinion.

@haukepetersen haukepetersen force-pushed the opt_driver_ata8520e-doc branch from 8a025a5 to c3ccdc5 Compare January 30, 2018 16:27
@haukepetersen
Copy link
Copy Markdown
Contributor Author

removed those indention fixes. Will open a separate PR with those changes to have this discussion sorted out once and for all :-)

So this PR should be ready for merge, right?

Copy link
Copy Markdown
Contributor

@aabadie aabadie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed those indention fixes.

Thanks

removed those indention fixes. Will open a separate PR with those changes to have this discussion sorted out once and for all

Better opening an issue for this because this is not only applicable to this specific driver.

Otherwise ACK and go !

@aabadie aabadie merged commit bf7239c into RIOT-OS:master Jan 30, 2018
@haukepetersen haukepetersen deleted the opt_driver_ata8520e-doc branch January 30, 2018 17:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Area: doc Area: Documentation Area: drivers Area: Device drivers CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR Impact: minor The PR is small in size and might only require a quick look of a knowledgeable reviewer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants