Documentation: hardware_uart #1219

New issue

Closed

opened 2023-02-04 14:32:21 -06:00 by bradselb · 3 comments

bradselb commented

2023-02-04 14:32:21 -06:00

(Migrated from github.com)

The description for uart_read_blocking() says: "This function will block until all the data has been received from the UART". It is somewhat ambiguous what is meant by "all the data". The function actually blocks until len (the third parameter) characters are read. May I suggest, "This function blocks until len characters have been read".
The function: bool uart_is_readable() returns a bool but the description says that it returns the number of bytes with the observation that the number of bytes can only be zero or one. May I suggest something like, "Returns true if a character can be read, otherwise returns false." The description for bool uart_is_writable() gets this right.

1. The description for uart_read_blocking() says: "This function will block until all the data has been received from the UART". It is somewhat ambiguous what is meant by "all the data". The function actually blocks until len (the third parameter) characters are read. May I suggest, "This function blocks until len characters have been read". 2. The function: bool uart_is_readable() returns a bool but the description says that it returns the number of bytes with the observation that the number of bytes can only be zero or one. May I suggest something like, "Returns true if a character can be read, otherwise returns false." The description for bool uart_is_writable() gets this right.

bradselb commented

2023-02-04 17:47:39 -06:00

(Migrated from github.com)

Are these steps about right?

Navigate to https://github.com/raspberrypi/pico-sdk/
click the Fork button and uncheck the check box next to "Copy the Master branch only"
open a terminal emulator on my local (plain vanilla Debian Linux) machine
mkdir pico-sdk-contrib
cd pico-sdk-contrib
git clone https://github.com/bradselb/pico-sdk.git .
git remote -v
git remote add upstream https://github.com/raspberrypi/pico-sdk.git
git checkout develop
make edits to comments in header file
compile, test, etc.
git commit -m "revise comments in header file to improve SDK documentation"
git push
open a pull request

It looks like I could contribute a fix - its a small change to comments in a header file - but, I've never contributed to an open source project. I'm mainly unclear on whether to create my own branch or work in the existing develop branch. Are these steps about right? 1. Navigate to https://github.com/raspberrypi/pico-sdk/ 2. click the Fork button and uncheck the check box next to "Copy the Master branch only" 3. open a terminal emulator on my local (plain vanilla Debian Linux) machine 4. mkdir pico-sdk-contrib 5. cd pico-sdk-contrib 6. git clone https://github.com/bradselb/pico-sdk.git . 7. git remote -v 8. git remote add upstream https://github.com/raspberrypi/pico-sdk.git 9. git checkout develop 10. make edits to comments in header file 11. compile, test, etc. 12. git commit -m "revise comments in header file to improve SDK documentation" 13. git push 14. open a pull request

kosmas12 commented

2023-02-05 03:55:23 -06:00

(Migrated from github.com)

It's best to create a new branch for your contribution but that's about right. Make a fork, clone it into some directory, make a new branch, do your thing in said branch, test, commit, push and open a PR.

bradselb commented

2023-02-05 08:34:54 -06:00

(Migrated from github.com)