[Bug]: Documentation bug, "WOLFSSL_ERROR_ZERO_RETURN" has no description

[ell1e]

Contact Details

No response

Version

latest documentation here: https://docs.rs/wolfssl-sys/latest/

Description

The entry for WOLFSSL_ERROR_ZERO_RETURN in the listing of constants https://docs.rs/wolfssl-sys/latest/wolfssl_sys/constant.WOLFSSL_ERROR_ZERO_RETURN.html has no short description what the constant means. This would make it easier to navigate the documentation for this value. I'm not suggesting a longer explanation like a tutorial, just 1-2 short sentences about the purpose that make it easier to locate tutorials etc. related to the purpose of this constant.

I've seen this constant being used in the example echoserver code without it being too obvious to me what it means. (Usually no returned value from a non-blocking socket would either be an EWOULDBLOCK situation, or the socket would be closed, wouldn't it? This seems to be some third possibility.) I'm sure it's somewhere in the tutorials, but people looking up the constant itself will likely end up in the API listing first.

Sorry if there is a short description on this API listing page after all and I somehow managed to hide it or not see it.

Reproduction steps

1. Open up https://docs.rs/wolfssl-sys/latest/wolfssl_sys/constant.WOLFSSL_ERROR_ZERO_RETURN.html which is perhaps where you might land when searching for the constant after seeing it in the example code

2. Figure out that you can't really see any info about what it's purpose is, not even a one sentence description that gives you a good starting point

Relevant log output

[anhu]

Hello @ell1e ,
Thank you very much for reaching out to us. It is true that there is little documentation with regards to this particular return code. Please let me explain why. Note this explanation is NOT a justification, its letting you know why the situation occurred.

That return code was brought into wolfSSL as part of the OpenSSL Compatibility Layer; you'll find a similar return code in OpenSSL. Normally, for things in the compatibility layer, we see little demand for documentation because the code that uses it is already written. As such, with little demand, it doesn't get the highest priority.

However, now that you have brought this to our attention, I shall endeavour to write a comment about this value in the wolfSSL header files. Please stay tuned.

Warm regards, Anthony

[anhu]

In the meantime can you let us know a bit about yourself and your project? For example, is this out of professional, academic or personal interest?

Warm regards, Anthony

[ell1e]

I'm looking to integrate TLS into the standard library of the language project I'm working on. Due to licensing issues I may go with a different library, but at that point I had already started reading up on WolfSSL and I like to help out other projects with documentation. Therefore I'm happy to provide suggestions on how to make this understandable, even if I end up using a different library. And it seems like a lot of TLS libraries implement common functionality similarly anyway.

[anhu]

Right now, I'm in the middle of adding some simple comments around these values.

In terms of licensing, if you get the code from github, its licensed under GPL. That said, we offer wolfSSL under a dual license model. If you need a commercial license I can put you in touch with the appropriate wolfSSL Business Director. Please do let me know if you are interested in commercial licensing.

Warm regards, Anthony

[anhu]

Please have a look at #8365