OSSL_STORE_LOADER_free() has conflicting documentation
jordanbrown0 opened this issue · comments
While reviewing documentation for #24675, I find that OSSL_STORE_LOADER_free() is documented in OSSL_STORE_LOADER.pod as both a current function and as a deprecated function, with the same signature.
void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader);
void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);
OSSL_STORE_LOADER_free() frees the given I<store_loader>.
... OSSL_STORE_LOADER_free(), ... were added in OpenSSL 3.0.
... OSSL_STORE_LOADER_free(), ... were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0.
I am not sure whether this function got deleted and re-created, or what. It seems to me that the right answer is to remove the "deprecated" side, and modify the history to say that it was added in 1.1.1. Maybe have the history say that in 3.0 it was changed to use a reference counter.
Im not sure I'd go so far to say that its listed as both deprecated and not deprecated, but references o the function difinately seem to be off in the pod file (for instance its listed in the history section as being introduced both in 3.0 and 1.1)
Either way, it seems some doc cleanup is warranted here. Are you interested in writing a PR to clean this up? I'm happy to assign it to you
I think it would be better if it was somebody who understands the actual history and how the "old" functions relate to the "new" functions.
But yeah, it really is listed as both normal and deprecated. Perhaps it wasn't obvious enough in my extracts, but it's listed both in the "main" block under SYNOPSIS and in the "following functions have been deprecated since OpenSSL 3.0" section below that (third from the bottom).
Note also that the HISTORY block says that the type OSSL_STORE_LOADER was deprecated in OpenSSL 3.0, but it's defined in the "main" block and used by every function in that block.
Those are documentation bugs, thanks for finding them!
@jordanbrown0, can I ask you to review #24680, to see if I've missed something?