From 50ef944cd66135d90ab71d9dcce0ca7cfbc44aca Mon Sep 17 00:00:00 2001 From: Michael Baentsch <57787676+baentsch@users.noreply.github.com> Date: Mon, 16 Dec 2024 08:16:42 +0100 Subject: [PATCH] Fix missing HISTORY doc entries Also add a check to find-doc-nits for HISTORY sections. Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/26188) --- Configurations/unix-Makefile.tmpl | 2 +- doc/HOWTO/documenting-functions-and-macros.md | 7 +++ doc/man3/ASYNC_start_job.pod | 2 + doc/man3/BIO_get_rpoll_descriptor.pod | 4 +- doc/man3/BIO_s_dgram_pair.pod | 6 ++- doc/man3/BIO_s_mem.pod | 2 +- doc/man3/CRYPTO_THREAD_run_once.pod | 6 ++- doc/man3/EC_GROUP_new.pod | 4 +- doc/man3/ERR_set_mark.pod | 3 +- doc/man3/EVP_PKEY_CTX_get_algor.pod | 4 ++ doc/man3/OPENSSL_LH_COMPFUNC.pod | 3 ++ doc/man3/OPENSSL_malloc.pod | 3 +- doc/man3/PEM_read_bio_PrivateKey.pod | 3 ++ doc/man3/PKCS12_SAFEBAG_set0_attrs.pod | 6 ++- doc/man3/SSL_get1_builtin_sigalgs.pod | 2 +- doc/man3/X509V3_get_d2i.pod | 5 ++ doc/man3/X509_dup.pod | 52 +++++++++++++++++++ doc/man3/X509_get0_notBefore.pod | 8 +-- doc/man3/X509_get_subject_name.pod | 3 ++ doc/man3/X509_get_version.pod | 3 ++ doc/man3/d2i_X509.pod | 36 +++++++++++++ util/find-doc-nits | 46 +++++++++++++++- 22 files changed, 195 insertions(+), 15 deletions(-) diff --git a/Configurations/unix-Makefile.tmpl b/Configurations/unix-Makefile.tmpl index 09303c42dfd6d..91e2646580857 100644 --- a/Configurations/unix-Makefile.tmpl +++ b/Configurations/unix-Makefile.tmpl @@ -1173,7 +1173,7 @@ generate_buildinfo: generate_doc_buildinfo .PHONY: doc-nits md-nits doc-nits: build_generated_pods ## Evaluate OpenSSL documentation - $(PERL) $(SRCDIR)/util/find-doc-nits -c -n -l -e + $(PERL) $(SRCDIR)/util/find-doc-nits -c -n -l -e -i # This uses "mdl", the markdownlint application, which is written in ruby. # The source is at https://github.com/markdownlint/markdownlint diff --git a/doc/HOWTO/documenting-functions-and-macros.md b/doc/HOWTO/documenting-functions-and-macros.md index 7256690d3c8dc..9ee2446316d4e 100644 --- a/doc/HOWTO/documenting-functions-and-macros.md +++ b/doc/HOWTO/documenting-functions-and-macros.md @@ -168,6 +168,13 @@ include/openssl/bio.h: macro BIO_set_dgram_bar(3) undocumented make: *** [Makefile:3833: doc-nits] Error 1 ``` +Additionally, public symbols added should contain an entry in the HISTORY +section of their documentation explaining the exact OpenSSL version in which +they have appeared for the first time. The option -i for "find-doc-nits" +can be utilized to check for this. A completely new documentation file +should also contain a HISTORY section with wording along this line, e.g. +"These functions have been added in OpenSSL version xxx.". + Summary ------- diff --git a/doc/man3/ASYNC_start_job.pod b/doc/man3/ASYNC_start_job.pod index 2b0be4daf8f76..89b34ae6a4372 100644 --- a/doc/man3/ASYNC_start_job.pod +++ b/doc/man3/ASYNC_start_job.pod @@ -363,6 +363,8 @@ ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(), ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first added in OpenSSL 1.1.0. +ASYNC_set_mem_functions(), ASYNC_get_mem_functions() were added +in OpenSSL 3.2. =head1 COPYRIGHT diff --git a/doc/man3/BIO_get_rpoll_descriptor.pod b/doc/man3/BIO_get_rpoll_descriptor.pod index e5712fb90fa51..635063deb495f 100644 --- a/doc/man3/BIO_get_rpoll_descriptor.pod +++ b/doc/man3/BIO_get_rpoll_descriptor.pod @@ -97,12 +97,12 @@ L, L =head1 HISTORY -The SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() functions were +The BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() functions were added in OpenSSL 3.2. =head1 COPYRIGHT -Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved. Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/BIO_s_dgram_pair.pod b/doc/man3/BIO_s_dgram_pair.pod index b0f52af05d760..bcd70de48c309 100644 --- a/doc/man3/BIO_s_dgram_pair.pod +++ b/doc/man3/BIO_s_dgram_pair.pod @@ -210,9 +210,13 @@ operation is not supported. L, L +=head1 HISTORY + +BIO_s_dgram_pair(), BIO_new_bio_dgram_pair() were added in OpenSSL 3.2. + =head1 COPYRIGHT -Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved. Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/BIO_s_mem.pod b/doc/man3/BIO_s_mem.pod index 23631800d5e56..f9385672985a6 100644 --- a/doc/man3/BIO_s_mem.pod +++ b/doc/man3/BIO_s_mem.pod @@ -203,7 +203,7 @@ BIO_s_dgram_mem() was added in OpenSSL 3.2. =head1 COPYRIGHT -Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved. Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod index 571e86fd47d0b..e977b91e862e4 100644 --- a/doc/man3/CRYPTO_THREAD_run_once.pod +++ b/doc/man3/CRYPTO_THREAD_run_once.pod @@ -267,7 +267,11 @@ L, L. =head1 HISTORY -CRYPTO_atomic_store() was added in OpenSSL 3.4.0 +CRYPTO_atomic_load_int(), OSSL_set_max_threads(), OSSL_get_max_threads(), +OSSL_get_thread_support_flags() were added in OpenSSL 3.2. + +CRYPTO_atomic_store(), CRYPTO_atomic_add64(), CRYPTO_atomic_and() +were added in OpenSSL 3.4. =head1 COPYRIGHT diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod index 26c0088435f43..6c6b61af8aa3c 100644 --- a/doc/man3/EC_GROUP_new.pod +++ b/doc/man3/EC_GROUP_new.pod @@ -212,6 +212,8 @@ L, L =head1 HISTORY +EC_GROUP_to_params() was added in OpenSSL 3.2. + =over 2 =item * @@ -236,7 +238,7 @@ instead. =head1 COPYRIGHT -Copyright 2013-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-2024 The OpenSSL Project Authors. All Rights Reserved. Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/ERR_set_mark.pod b/doc/man3/ERR_set_mark.pod index 070a7f6e2938f..a067d6db70049 100644 --- a/doc/man3/ERR_set_mark.pod +++ b/doc/man3/ERR_set_mark.pod @@ -46,11 +46,12 @@ ERR_pop() returns 1 if an error was popped or 0 if the error stack was empty. =head1 HISTORY +ERR_count_to_mark() was added in OpenSSL 3.2. ERR_pop() was added in OpenSSL 3.3. =head1 COPYRIGHT -Copyright 2003-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2003-2024 The OpenSSL Project Authors. All Rights Reserved. Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/EVP_PKEY_CTX_get_algor.pod b/doc/man3/EVP_PKEY_CTX_get_algor.pod index be408c1c52c34..c025be4c816a2 100644 --- a/doc/man3/EVP_PKEY_CTX_get_algor.pod +++ b/doc/man3/EVP_PKEY_CTX_get_algor.pod @@ -64,6 +64,10 @@ All functions return 1 for success, and 0 or a negative number if an error occurs. In particular, -2 is returned when the function isn't supported by the B> implementation. +=head1 HISTORY + +These functions were added in OpenSSL 3.4. + =head1 COPYRIGHT Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod index 772f421303a69..7812cc2348ad4 100644 --- a/doc/man3/OPENSSL_LH_COMPFUNC.pod +++ b/doc/man3/OPENSSL_LH_COMPFUNC.pod @@ -324,6 +324,9 @@ type checking. In OpenSSL 3.1, B() was introduced and B() was deprecated. +OPENSSL_LH_doall_arg_thunk(), OPENSSL_LH_set_thunks() were added in +OpenSSL 3.3. + =head1 COPYRIGHT Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index fccf3bd788da2..d02eb47e9a6e4 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -249,7 +249,8 @@ CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(), CRYPTO_mem_ctrl() were deprecated in OpenSSL 3.0. The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of clang's memory and leak sanitizer. -OPENSSL_aligned_alloc(), CRYPTO_aligned_alloc() were added in OpenSSL 3.4.0 +OPENSSL_aligned_alloc(), CRYPTO_aligned_alloc(), OPENSSL_strtoul() were +added in OpenSSL 3.4. =head1 COPYRIGHT diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod index 9d85d4438a37b..22a5d606b0dbd 100644 --- a/doc/man3/PEM_read_bio_PrivateKey.pod +++ b/doc/man3/PEM_read_bio_PrivateKey.pod @@ -585,6 +585,9 @@ PEM_write_bio_DSAparams(), PEM_write_DSAparams(), PEM_read_bio_DHparams(), PEM_read_DHparams(), PEM_write_bio_DHparams() and PEM_write_DHparams() were deprecated in 3.0. +PEM_read_bio_X509_ACERT(), PEM_read_X509_ACERT(), +PEM_write_bio_X509_ACERT(), PEM_write_X509_ACERT() +were added in OpenSSL 3.4. =head1 COPYRIGHT diff --git a/doc/man3/PKCS12_SAFEBAG_set0_attrs.pod b/doc/man3/PKCS12_SAFEBAG_set0_attrs.pod index 7b45deb471faa..5f53fba1718cf 100644 --- a/doc/man3/PKCS12_SAFEBAG_set0_attrs.pod +++ b/doc/man3/PKCS12_SAFEBAG_set0_attrs.pod @@ -20,9 +20,13 @@ PKCS#12 safeBag. I is the B to assign the attributes to. PKCS12_SAFEBAG_set0_attrs() does not return a value. +=head1 HISTORY + +This function was added in OpenSSL 3.2. + =head1 COPYRIGHT -Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/SSL_get1_builtin_sigalgs.pod b/doc/man3/SSL_get1_builtin_sigalgs.pod index 98e541bc6ae1f..2329d6a9fe73d 100644 --- a/doc/man3/SSL_get1_builtin_sigalgs.pod +++ b/doc/man3/SSL_get1_builtin_sigalgs.pod @@ -28,7 +28,7 @@ newly allocated string is always returned but it may have strlen == 0. =head1 HISTORY -This call was added in OpenSSL 3.4. +This function was added in OpenSSL 3.4. =head1 COPYRIGHT diff --git a/doc/man3/X509V3_get_d2i.pod b/doc/man3/X509V3_get_d2i.pod index 864666661148b..330464e0c8da8 100644 --- a/doc/man3/X509V3_get_d2i.pod +++ b/doc/man3/X509V3_get_d2i.pod @@ -246,6 +246,11 @@ L, L, L +=head1 HISTORY + +X509_ACERT_get_ext_d2i(), X509_ACERT_add1_ext_i2d(), +X509_ACERT_get0_extensions() were added in OpenSSL 3.4. + =head1 COPYRIGHT Copyright 2015-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/X509_dup.pod b/doc/man3/X509_dup.pod index 8005de17e40ed..f34de42a25b0b 100644 --- a/doc/man3/X509_dup.pod +++ b/doc/man3/X509_dup.pod @@ -505,6 +505,58 @@ CMS_ContentInfo_new_ex() were added in OpenSSL 3.0. The functions DSAparams_dup(), RSAPrivateKey_dup() and RSAPublicKey_dup() were deprecated in 3.0. +CMS_EnvelopedData_it(), CMS_SignedData_free(), CMS_SignedData_new() +were added in OpenSSL 3.2. + +DIST_POINT_NAME_dup(), OSSL_IETF_ATTR_SYNTAX_free(), OSSL_IETF_ATTR_SYNTAX_it(), +OSSL_IETF_ATTR_SYNTAX_new(), OSSL_ATTRIBUTES_SYNTAX_free(), +OSSL_ATTRIBUTES_SYNTAX_it(), OSSL_ATTRIBUTES_SYNTAX_new(), +OSSL_BASIC_ATTR_CONSTRAINTS_free(), OSSL_BASIC_ATTR_CONSTRAINTS_it(), +OSSL_BASIC_ATTR_CONSTRAINTS_new(), OSSL_CMP_ATAVS_new(), OSSL_CMP_ATAVS_free(), +OSSL_CMP_ATAVS_it(), OSSL_CMP_CRLSTATUS_free(), OSSL_CRMF_CERTTEMPLATE_dup(), +OSSL_CRMF_ATTRIBUTETYPEANDVALUE_dup(), OSSL_CRMF_ATTRIBUTETYPEANDVALUE_free(), +OSSL_TARGET_free(), OSSL_TARGET_it(), OSSL_TARGET_new(), +OSSL_TARGETING_INFORMATION_free(), OSSL_TARGETING_INFORMATION_it(), +OSSL_TARGETING_INFORMATION_new(), OSSL_TARGETS_free(), +OSSL_TARGETS_it(), OSSL_TARGETS_new(), OSSL_IETF_ATTR_SYNTAX_VALUE_free(), +OSSL_IETF_ATTR_SYNTAX_VALUE_it(), OSSL_IETF_ATTR_SYNTAX_VALUE_new(), +OSSL_ISSUER_SERIAL_free(), OSSL_ISSUER_SERIAL_new(), +OSSL_OBJECT_DIGEST_INFO_free(), OSSL_OBJECT_DIGEST_INFO_new(), +OSSL_USER_NOTICE_SYNTAX_free(), OSSL_USER_NOTICE_SYNTAX_new(), +OSSL_USER_NOTICE_SYNTAX_it(), PBMAC1PARAM_free(), PBMAC1PARAM_it(), +PBMAC1PARAM_new(), X509_ACERT_dup(), X509_ACERT_free(), X509_ACERT_it(), +X509_ACERT_new(), X509_ACERT_INFO_free(), X509_ACERT_INFO_it(), +X509_ACERT_INFO_new(), X509_ACERT_ISSUER_V2FORM_free(), +X509_ACERT_ISSUER_V2FORM_new() +were added in OpenSSL 3.4. + +OSSL_ATTRIBUTE_DESCRIPTOR_free(), OSSL_ATTRIBUTE_DESCRIPTOR_new(), +OSSL_ATTRIBUTE_DESCRIPTOR_it(), OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_free(), +OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_it(), OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_new(), +OSSL_HASH_free(), OSSL_HASH_it(), OSSL_HASH_new(), OSSL_INFO_SYNTAX_free(), +OSSL_INFO_SYNTAX_it(), OSSL_INFO_SYNTAX_new(), OSSL_INFO_SYNTAX_POINTER_free(), +OSSL_INFO_SYNTAX_POINTER_it(), OSSL_INFO_SYNTAX_POINTER_new(), +OSSL_PRIVILEGE_POLICY_ID_free(), OSSL_PRIVILEGE_POLICY_ID_it(), +OSSL_PRIVILEGE_POLICY_ID_new(), OSSL_ROLE_SPEC_CERT_ID_free(), +OSSL_ROLE_SPEC_CERT_ID_new(), OSSL_ROLE_SPEC_CERT_ID_it(), +OSSL_ROLE_SPEC_CERT_ID_SYNTAX_free(), OSSL_ROLE_SPEC_CERT_ID_SYNTAX_new(), +OSSL_ROLE_SPEC_CERT_ID_SYNTAX_it(), OSSL_DAY_TIME_BAND_free(), +OSSL_DAY_TIME_BAND_it(), OSSL_DAY_TIME_BAND_new(), +OSSL_DAY_TIME_free(), OSSL_DAY_TIME_it(), OSSL_DAY_TIME_new(), +OSSL_NAMED_DAY_free(), OSSL_NAMED_DAY_it(), OSSL_NAMED_DAY_new(), +OSSL_TIME_PERIOD_free(), OSSL_TIME_PERIOD_it(), OSSL_TIME_PERIOD_new(), +OSSL_TIME_SPEC_ABSOLUTE_free(), OSSL_TIME_SPEC_ABSOLUTE_it(), +OSSL_TIME_SPEC_ABSOLUTE_new(), OSSL_TIME_SPEC_DAY_free(), +OSSL_TIME_SPEC_DAY_it(), OSSL_TIME_SPEC_DAY_new(), +OSSL_TIME_SPEC_MONTH_free(), OSSL_TIME_SPEC_MONTH_it(), +OSSL_TIME_SPEC_MONTH_new(), OSSL_TIME_SPEC_TIME_free(), +OSSL_TIME_SPEC_TIME_it(), OSSL_TIME_SPEC_TIME_new(), +OSSL_TIME_SPEC_WEEKS_free(), OSSL_TIME_SPEC_WEEKS_it(), +OSSL_TIME_SPEC_WEEKS_new(), OSSL_TIME_SPEC_X_DAY_OF_free(), +OSSL_TIME_SPEC_X_DAY_OF_it(), OSSL_TIME_SPEC_X_DAY_OF_new(), +OSSL_TIME_SPEC_free(), OSSL_TIME_SPEC_it(), OSSL_TIME_SPEC_new() +were added in OpenSSL 3.5. + =head1 COPYRIGHT Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/X509_get0_notBefore.pod b/doc/man3/X509_get0_notBefore.pod index 628ad7bc0cb32..1d94729277b53 100644 --- a/doc/man3/X509_get0_notBefore.pod +++ b/doc/man3/X509_get0_notBefore.pod @@ -113,10 +113,12 @@ L =head1 HISTORY -These functions are available in all versions of OpenSSL. - X509_get_notBefore() and X509_get_notAfter() were deprecated in OpenSSL -1.1.0 +1.1.0. + +X509_ACERT_get0_notBefore(), X509_ACERT_get0_notAfter(), +X509_ACERT_set1_notBefore(), X509_ACERT_set1_notAfter() +were added in OpenSSL 3.4. =head1 COPYRIGHT diff --git a/doc/man3/X509_get_subject_name.pod b/doc/man3/X509_get_subject_name.pod index 6a10878d33832..56c5404a439d1 100644 --- a/doc/man3/X509_get_subject_name.pod +++ b/doc/man3/X509_get_subject_name.pod @@ -127,6 +127,9 @@ added in OpenSSL 1.0.0 as a macro. X509_NAME_hash() was turned into a macro and deprecated in OpenSSL 3.0. +X509_ACERT_get0_issuerName(), X509_ACERT_set1_issuerName() +were added in OpenSSL 3.4. + =head1 COPYRIGHT Copyright 2015-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/X509_get_version.pod b/doc/man3/X509_get_version.pod index 6eb29e7aed7ed..23e1f5a9623c6 100644 --- a/doc/man3/X509_get_version.pod +++ b/doc/man3/X509_get_version.pod @@ -81,6 +81,9 @@ L X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version() are functions in OpenSSL 1.1.0, in previous versions they were macros. +X509_ACERT_get_version(), X509_ACERT_set_version() +were added in OpenSSL 3.4. + =head1 COPYRIGHT Copyright 2015-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index b454954b5e30a..934ccab587665 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -683,6 +683,42 @@ structure has been modified after deserialization or previous serialization. This is because some objects cache the encoding for efficiency reasons. +=head1 HISTORY + +d2i_OSSL_ATTRIBUTES_SYNTAX(), d2i_OSSL_BASIC_ATTR_CONSTRAINTS(), +d2i_OSSL_CMP_ATAVS(), d2i_OSSL_IETF_ATTR_SYNTAX(), +d2i_OSSL_TARGET(), d2i_OSSL_TARGETING_INFORMATION(), +d2i_OSSL_TARGETS(), d2i_OSSL_USER_NOTICE_SYNTAX(), +d2i_PBMAC1PARAM(), d2i_X509_ACERT(), d2i_X509_ACERT_bio(), +d2i_X509_ACERT_fp(), i2d_OSSL_ATTRIBUTES_SYNTAX(), +i2d_OSSL_BASIC_ATTR_CONSTRAINTS(), i2d_OSSL_CMP_ATAVS(), +i2d_OSSL_IETF_ATTR_SYNTAX(), i2d_OSSL_TARGET(), +i2d_OSSL_TARGETING_INFORMATION(), i2d_OSSL_TARGETS(), +i2d_OSSL_USER_NOTICE_SYNTAX(), i2d_PBMAC1PARAM(), i2d_X509_ACERT(), +i2d_X509_ACERT_bio(), i2d_X509_ACERT_fp() +were added in OpenSSL 3.4. + +d2i_OSSL_ATTRIBUTE_DESCRIPTOR(), d2i_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX(), +d2i_OSSL_HASH(), d2i_OSSL_INFO_SYNTAX(), +d2i_OSSL_INFO_SYNTAX_POINTER(), d2i_OSSL_PRIVILEGE_POLICY_ID(), +d2i_OSSL_ROLE_SPEC_CERT_ID(), d2i_OSSL_ROLE_SPEC_CERT_ID_SYNTAX(), +i2d_OSSL_ATTRIBUTE_DESCRIPTOR(), i2d_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX(), +i2d_OSSL_HASH(), i2d_OSSL_INFO_SYNTAX(), +i2d_OSSL_INFO_SYNTAX_POINTER(), i2d_OSSL_PRIVILEGE_POLICY_ID(), +i2d_OSSL_ROLE_SPEC_CERT_ID(), i2d_OSSL_ROLE_SPEC_CERT_ID_SYNTAX(), +d2i_OSSL_DAY_TIME(), d2i_OSSL_DAY_TIME_BAND(), d2i_OSSL_NAMED_DAY(), +d2i_OSSL_TIME_PERIOD(), d2i_OSSL_TIME_SPEC(), +d2i_OSSL_TIME_SPEC_ABSOLUTE(), d2i_OSSL_TIME_SPEC_DAY(), +d2i_OSSL_TIME_SPEC_MONTH(), d2i_OSSL_TIME_SPEC_TIME(), +d2i_OSSL_TIME_SPEC_WEEKS(), d2i_OSSL_TIME_SPEC_X_DAY_OF(), +i2d_OSSL_DAY_TIME(), i2d_OSSL_DAY_TIME_BAND(), +i2d_OSSL_NAMED_DAY(), i2d_OSSL_TIME_PERIOD(), +i2d_OSSL_TIME_SPEC(), i2d_OSSL_TIME_SPEC_ABSOLUTE(), +i2d_OSSL_TIME_SPEC_DAY(), i2d_OSSL_TIME_SPEC_MONTH(), +i2d_OSSL_TIME_SPEC_TIME(), i2d_OSSL_TIME_SPEC_WEEKS(), +i2d_OSSL_TIME_SPEC_X_DAY_OF() +were added in OpenSSL 3.5. + =head1 COPYRIGHT Copyright 1998-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/util/find-doc-nits b/util/find-doc-nits index 7d1cdb59b1dbd..8a5c26fb61b12 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -41,6 +41,7 @@ our($opt_p); our($opt_u); our($opt_v); our($opt_c); +our($opt_i); # Print usage message and exit. sub help { @@ -54,13 +55,14 @@ Find small errors (nits) in documentation. Options: -m Name(s) of manuals to focus on. Default: man1,man3,man5,man7 -n Print nits in POD pages -o Causes -e/-v to count symbols added since 1.1.1 as new (implies -v) + -i Checks for history entries available for symbols added since 3.0.0 as new -u Count undocumented functions -v Count new undocumented functions EOF exit; } -getopts('cdehlm:nouv'); +getopts('cdehlm:noiuv'); help() if $opt_h; $opt_u = 1 if $opt_d; @@ -433,6 +435,29 @@ sub check_section_location { if $contents =~ /=head1 $before.*=head1 $section/ms; } +# Check if HISTORY section is present and functionname ($2) is present in it +# or a generic "(f)unction* added" term hints at several new functions in +# the documentation (yes, this is an approximation only but it works :) +sub find_functionname_in_history_section { + my $contents = shift; + my $functionname = shift; + my (undef, $rest) = split('=head1 HISTORY\s*', $contents); + + if (not $rest) { + # No HISTORY section is a clear error now + return 0; + } + else { + my ($histsect, undef) = split('=head1 COPYRIGHT\s*', $rest); + if (index($histsect, $functionname) == -1) { + # OK, functionname is not in HISTORY section... + # last try: Check for presence of "*unction*added*" + return 0 if (not $histsect =~ /unction.*added.*/g); + } + } + return 1; +} + # Check if a =head1 is duplicated, or a =headX is duplicated within a # =head1. Treats =head2 =head3 as equivalent -- it doesn't reset the head3 # sets if it finds a =head2 -- but that is good enough for now. Also check @@ -842,6 +867,8 @@ my %name_map = (); # Any of these values except 'public' may be prefixed with 'missing_' # to indicate that they are known to be missing. my %state; +# history contains the same as state above for entries with version info != 3_0_0 +my %history; # %missing is affected by loading util/missing*.txt. Values may be one of: # 'crypto' : belongs in libcrypto (loaded from libcrypto.num) # 'ssl' : belongs in libssl (loaded from libssl.num) @@ -862,6 +889,12 @@ sub loadnum ($;$) { next if /^#/; next if /\bNOEXIST\b/; my @fields = split(); + if ($type && ($type eq "crypto" || $type eq "ssl")) { + # 3rd field is version + if (not $fields[2] eq "3_0_0") { + $history{$fields[0].'(3)'} = $type.$fields[2]; + } + } die "Malformed line $. in $file: $_" if scalar @fields != 2 && scalar @fields != 4; $state{$fields[0].'(3)'} = $type // 'internal'; @@ -952,6 +985,8 @@ sub printem ($) { my $count = 0; foreach my $func ( grep { $state{$_} eq $type } sort keys %state ) { + err("$type:", "function $func not in any history section") + if ($opt_i && defined $history{$func}); next if defined $name_map{$func} || defined $missing{$func}; @@ -984,6 +1019,15 @@ sub collectnames { my $name_sec = "$name($section)"; if ( !defined $name_map{$name_sec} ) { $name_map{$name_sec} = $filename; + if ($history{$name_sec}) { + my $funcname = $name_sec; + my $contents = $podinfo{contents}; + $funcname =~ s/\(.*//; + if (find_functionname_in_history_section($contents, $funcname)) { + # mark this function as found/no longer of interest + $history{$name_sec} = undef; + } + } $state{$name_sec} //= ( $filename =~ /\/internal\// ? 'internal' : 'public' ) if $is_generic;