Skip to content

Add API documentation for the C API - #33

Merged
Duncan Horn (dunhor) merged 11 commits into
microsoft:mainfrom
jspanjers:add-api-docs
Nov 6, 2026
Merged

Duncan Horn (dunhor) merged 11 commits into
microsoft:mainfrom
jspanjers:add-api-docs

Conversation

@jspanjers

Copy link
Copy Markdown
Contributor

No description provided.

@jspanjers

Copy link
Copy Markdown
Contributor Author

@microsoft-github-policy-service agree

@dunhor Duncan Horn (dunhor) left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please run clang-format (see comment). On that note, the column length for the project is set to 130 characters:

ColumnLimit: 130
It would be great if lines could be wrapped at that length (or let clang-format do it for you)

Comment thread src/include/inflatelib.h Outdated
Comment on lines +29 to +35
* // Initialize outputBuffer
* size_t outputBufferSize = 4096;
* char *outputBuffer = malloc(outputBufferSize);
* if (outputBuffer == NULL) {
* printf("Memory allocation failed.\n");
* return 1;
* }

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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);).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, I've added a patch.

Comment thread src/include/inflatelib.h Resolved
Comment thread src/include/inflatelib.h Resolved
Comment thread src/include/inflatelib.h Resolved
Comment thread src/include/inflatelib.h Outdated
Comment on lines +335 to +337
/**
* @}
*/ // End of RETURN_VALUES_GROUP

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, I've added a patch.

Comment thread src/include/inflatelib.h Outdated
Comment on lines +335 to +337
/**
* @}
*/ // End of RETURN_VALUES_GROUP

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, I've added a patch changing it to classic /* ... */ style comments.

Comment thread src/include/inflatelib.h Outdated
Comment on lines +360 to +361
* Verifies that the (major) version of the linked InflateLib library
* matches the (major) version of these library headers and initializes

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, I've added a patch.

Comment thread src/include/inflatelib.h Resolved
Comment thread src/include/inflatelib.h Outdated
*
* @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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@jspanjers
Jan-Joost Spanjers (jspanjers) marked this pull request as draft November 6, 2026 13:10

@dunhor Duncan Horn (dunhor) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@dunhor
Duncan Horn (dunhor) merged commit 175e025 into microsoft:main Nov 6, 2026
101 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants