Multiple suggestions for documentation improvements

[aral-matrix]

As mentioned in #482, I thought it best to move further ideas, unrelated to the previous question, to a new discussion:

Between documentation and the in-memory example, I failed to find a clear entry point for coding a wrapper class (my eventual implementation can be found here), because the library offers a means to open an archive from a file source directly, whereas the in-memory example focuses on loading the file contents into a manually allocated buffer, without going into much detail on the following (I am writing this down now as some of my memories of the initial struggle are coming back):

• why is zip_close called at all? The documentation states it "writes changes to disk" - in the meantime, I understand that actually it writes/commits changes to the underlying zip source, which can be a file, but doesn't have to be
• what's the point of this seemingly cumbersome reference count on zip sources, so that a manual call to keep is required on the source, before a close on the archive - this was probably one of the more confusing points, that calling a close on the "less important" archive structure will also invalidate the source, unless the reference count is manually increased first
• what is the meaning of zip_source_is_deleted in the first place? What does it mean that a zip source is "deleted" when, per documentation, the removal of all entries is only an example? What else would zip_source_is_deleted mean? And would a check for this ever be necessary unless it is possible per the calling program that the archive becomes empty?
• what could possibly go wrong in a call to zip_source_stat that the example checks for an error here? Is that a demonstration of how error checks should be done, or is there an actual failure condition to be checked after each call to zip_source_stat, similar to some stdlib functions?
• why does a zip source require opening for reading (via zip_source_open) after it has been created via zip_source_buffer_create (linking the archive data into it) and changes have been "committed" via zip_close? This question goes into the direction of a library architectural design description that I mentioned in one of my initial comments. Based on my understanding at this point, I would now explain this as "When a zip source is created, it is linked to one or more immutable (from the perspective of the zip source) data sources. Depending on the data source (disk or memory), a call to zip_close will write an updated archive to disk or to a newly allocated buffer in memory. This updated archive / buffer has to be explicitly readied for reading with a call to zip_source_open
• why is zip_close the only way to "commit" changes to an archive, immediately invalidating the zip archive? Why is there no means to commit changes to the destination (disk or buffer) without invalidating the archive itself, assuming the user still wants to work with it?
• what is the purpose of parameter archive in https://libzip.org/documentation/zip_source_buffer.html ? I get it now: the source is immediately associated with that archive - but that info is missing from documentation and it made it hard to understand initially, especially since an archive is created on a source, and here we have a source being created and depending on an archive, looking to the untrained eye like a hen-and-egg problem

Also, it would be really great if the documentation made use of notes and cautions, for example in
https://libzip.org/documentation/zip_source_buffer.html

Caution: data must remain valid for the lifetime of the created source. Modifying data before an archive is written (see zip_close) from the returned zip data source is UB.

Saying that because I initially missed this important bit, and with limited understanding of how the library worked, I assumed adding data to the archive would already copy it into internal data structures. I understand now that from a performance standpoint, this would not be desired behavior. But a visual cue could have saved me a few hours of debugging.

An example where the documentation is well done in terms of explaining what a function does is https://libzip.org/documentation/zip_source_stat.html - it has clear instructions for the purpose, work flow of invocation and return value(s).