# Processing Website Documentation (Serial)

**URL:** <https://discourse.processing.org/t/processing-website-documentation-serial/46343>\
**Category:** Site Feedback\
**Created:** [May 7, 2025, 7:29pm UTC](https://discourse.processing.org/t/processing-website-documentation-serial/46343 "2025-05-07T19:29:04Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![glv](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.processing.org/glv/32/18785_2.png) [@glv](https://discourse.processing.org/u/glv)\
**Post date:** [May 7, 2025, 7:29pm UTC](https://discourse.processing.org/t/processing-website-documentation-serial/46343/1 "2025-05-07T19:29:04Z")

</div>

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. 🙂

**Example 1**

The serial library documentation can be a challenge.

Consider two links (old and new):

- [Serial::readBytes()\ serial \ Language (API) \ Processing 1.0](https://www.andrew.cmu.edu/course/60-257/reference/libraries/serial/Serial_readBytes_.html)  
This has **byteBuffer** as a parameter in the description and syntax.

- [readBytes() / Libraries / Processing.org](https://processing.org/reference/libraries/serial/Serial_readBytes_.html)  
\*This has **byteBuffer** as a parameter in the description _ **but NOT in the syntax** _.  
The syntax uses a _ **dest** _ parameter _ **with NO description** _.

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](https://github.com/processing/processing4/blob/main/java/libraries/serial/src/processing/serial/Serial.java#L52C3-L52C35) 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:

```auto
byte[] inBuffer = new byte[7];

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

```

Some possible corrections:

Example 1

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

```

Example 2

```auto
byte[] inBuffer = new byte[7];
while (myPort.available() > 0) { 
    myPort.readBytes(inBuffer);
    if (inBuffer != null) {
      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](https://github.com/processing/processing4/tree/main/java/libraries/serial)_  
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:

> [@Processing to Arduino Serial Library Example](https://discourse.processing.org/t/processing-to-arduino-serial-library-example/11143/6):
>
> @glv – have you considered submitting this to the library, whether as a change to the original or as a “SimpleWrite2” example?

`:)`

---

<div class="post-metadata">

**Author:** ![sableraph](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.processing.org/sableraph/32/251_2.png) [@sableraph](https://discourse.processing.org/u/sableraph)\
**Post date:** [May 7, 2025, 7:59pm UTC](https://discourse.processing.org/t/processing-website-documentation-serial/46343/3 "2025-05-07T19:59:02Z")

</div>

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.

> [@glv](#):
>
> I may be able to contribute to this in the future.  
> How to get started on this?

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:

> <https://github.com/processing/processing4/blob/540d299cf39abee6b9de25db014d5d28be364032/java/libraries/serial/src/processing/serial/Serial.java#L348C1-L359C6>

### Reference Examples

Reference examples are handled separately, in the [processing-website repository](https://github.com/processing/processing-website/). You can find information about editing examples [here](https://github.com/processing/processing-website/blob/main/docs/reference.md#examples).

### Contributing

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

- An issue in the [**processing4**](https://github.com/processing/processing4/issues/new/choose) repository for the JavaDoc formatting
- A separate issue in the [**processing-website**](https://github.com/processing/processing-website/issues/new/choose) repository for the reference examples

I’ll be happy to assign them to you!

Let me know if you need any guidance.

Raphaël