Repository navigation
Add API documentation for the C API - #33
Conversation
|
@microsoft-github-policy-service agree |
There was a problem hiding this comment.
Please run clang-format (see comment). On that note, the column length for the project is set to 130 characters:
Line 43 in ed6546d
clang-format do it for you)
| * // Initialize outputBuffer | ||
| * size_t outputBufferSize = 4096; | ||
| * char *outputBuffer = malloc(outputBufferSize); | ||
| * if (outputBuffer == NULL) { | ||
| * printf("Memory allocation failed.\n"); | ||
| * return 1; | ||
| * } |
There was a problem hiding this comment.
For example code, brevity over full correctness is arguably more important. IMO this should either drop the error handling (null check) or switch to a stack array.
Note that the error handling for inflatelib API calls is fine and useful to include (though I'm more keen on something like printf("ERROR: %s", stream.error_msg);).
There was a problem hiding this comment.
Agreed, I've added a patch.
| /** | ||
| * @} | ||
| */ // End of RETURN_VALUES_GROUP |
There was a problem hiding this comment.
Looks like clang-format doesn't like this indentation being mis-matched with the lines below it... See https://github.com/microsoft/inflatelib/actions/runs/42119060376/job/127566494429?pr=33.
The long-term solution is to probably add IndentExternBlock: NoIndent to the .clang-format file, however I wouldn't necessarily suggest doing that now as it'll cause a lot of lines to change... Probably best to just let clang-format format it how it wants and I'll come back later and re-format the files.
There was a problem hiding this comment.
Agreed, I've added a patch.
| /** | ||
| * @} | ||
| */ // End of RETURN_VALUES_GROUP |
There was a problem hiding this comment.
Since this is a shared header consumers are intended to include, it's probably best to avoid line comments (//) for those compiling using older C standards.
There was a problem hiding this comment.
Agreed, I've added a patch changing it to classic /* ... */ style comments.
| * Verifies that the (major) version of the linked InflateLib library | ||
| * matches the (major) version of these library headers and initializes |
There was a problem hiding this comment.
Putting "major" in parenthesis feels unnecessary here and below. That's what it's doing - verifying that the major versions match - and that fact is important; consumers should be able to work with mismatched minor/patch versions.
There was a problem hiding this comment.
Agreed, I've added a patch.
| * | ||
| * @param[in,out] stream A pointer to an #inflatelib_stream either in the "initialized" or "Deflate" state. | ||
| * | ||
| * @retval #INFLATELIB_OK When there is still unprocessed input data left. |
There was a problem hiding this comment.
This phrasing seems potentially easy to mis-interpret. One possible reading is that this return value indicates not all bytes of next_in/avail_in have been read (mis-interpreting what "input data" means). One could also interpret that it means that the API is expecting to read more bytes from the input stream (mis-interpreting what "unprocessed" means), when that's not quite true: it will also get returned when all input data has been read, but not all output data has been written.
It would be less ambiguous to say that not all bytes of the stream have been fully processed (i.e. the negation of the INFLATELIB_EOF case).
Same thing for inflatelib_inflate64 below.
There was a problem hiding this comment.
Agreed, I've added a patch.
Co-authored-by: Duncan Horn <40036384+dunhor@users.noreply.github.com>
Co-authored-by: Duncan Horn <40036384+dunhor@users.noreply.github.com>
Co-authored-by: Duncan Horn <40036384+dunhor@users.noreply.github.com>
No description provided.