Processing Website Documentation (Serial)

Site Feedback
1

Hello folks,

There are some opportunities for improvement on the website documentation.

I am an experienced embedded C programmer and have had a chance to connect to Processing with the Processing Serial library (and others) and have been challenged with the documentation on this at times.

A thorough review and relevant updates to the site documentation are needed to ensure accuracy and clarity. And the source code?

As I like to say “Please be perspicuous in your communication”. < Humorous juxtaposition. :slight_smile:

Example 1

The serial library documentation can be a challenge.

Consider two links (old and new):

The description would benefit from NOT being a paragraph and in separate lines:

Reads a group of bytes from the buffer or null if there are none available.

The serial.readBytes() version with no parameters returns a byte array of all data in the buffer. This is not efficient, but is easy to use.

The serial.readBytes(byteBuffer) version with the byteBuffer parameter is more memory and time efficient. It grabs the data in the buffer and puts it into the byte array passed in and returns an int value for the number of bytes read. If more bytes are available than can fit into the byteBuffer , only those that fit are read.

It would also benefit from discussing what the buffer is; there is the serial buffer and also additional buffers (Windows and hardware that may be beyond the scope of this discussion).
Keeping in mind there is the serial buffer that has incoming data and there are the references to byteBuffer and inBuffer as well.

These are redundant calls and should be used separately and each have their own example:

byte[] inBuffer = new byte[7];

inBuffer = myPort.readBytes(); // This
myPort.readBytes(inBuffer);    // Or this but not both.

Some possible corrections:

Example 1

byte[] inBuffer = new byte[7];
while (myPort.available() > 0) {
    byte[] inBuffer = myPort.readBytes();
    if (inBuffer != null) {
      String myString = new String(inBuffer);
      println(myString);
    }
  }

Example 2

byte[] inBuffer = new byte[7];
if (myPort.available() > 0) {   //or while() ?
    myPort.readBytes(inBuffer);
    String myString = new String(inBuffer);
    println(myString);
  }

I have explored the above ad nauseum in the past and would have to revisit this again.
And revisit the source code:
processing4/java/libraries/serial at main · processing/processing4 · GitHub
I will leave that one for another day.

I may be able to contribute to this in the future.
How to get started on this?

Related:

:)

3

Hi @glv, thanks for raising these points.

Good to hear you’re getting some good use out of the Serial library despite the challenges with the documentation.

That would be wonderful! thanks for offering to help.

One important thing to know: the description text comes from the Processing4 repository (JavaDoc), while the reference examples are managed separately in the processing-website repository.

Description Text

The formatting of the serial.readBytes() description comes directly from the JavaDoc; specifically these lines:

Reference Examples

Reference examples are handled separately, in the processing-website repository. You can find information about editing examples here.

Contributing

If you’d like to contribute, feel free to open:

  • An issue in the processing4 repository for the JavaDoc formatting
  • A separate issue in the processing-website repository for the reference examples

I’ll be happy to assign them to you!

Let me know if you need any guidance.

Raphaël

1 Like