QuasarApp/openssl
4
0
Fork 0
mirror of https://github.com/QuasarApp/openssl.git synced 2025-04-28 02:34:40 +00:00
Code Issues Projects Releases Wiki Activity

POD: stop abusing comment

Browse Source 
OpenSSL uses some POD directives masquerading as 'comment'
('=for comment' etc).  This is abusive and confusing.  Instead, we use
our own keyword.

    =for openssl whatever

    =begin openssl

    whatever

    =end openssl

(we have never used the multiline form, but might start one day)

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10048)
This commit is contained in:
Richard Levitte 2019-09-29 17:10:59 +02:00
parent 59d0e6c896
commit bb82531f65
35 changed files with 36 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
View File

@ -9,7 +9,7 @@ ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include "crypto/sparse_array.h"

2
doc/internal/man3/ossl_param_bld_init.pod
View File

@ -15,7 +15,7 @@ ossl_param_bld_push_octet_ptr
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include "internal/params_build.h"

2
doc/man1/openssl-cmds.pod
View File

@ -55,7 +55,7 @@ x509
=head1 SYNOPSIS
=for comment generic
=for openssl generic
B<openssl> I<cmd> B<-help> | [I<-option> | I<-option> I<arg>] ... [I<arg>] ...

2
doc/man1/openssl-ts.pod
View File

@ -623,7 +623,7 @@ You could also look at the 'test' directory for more examples.
=head1 BUGS
=for comment foreign manuals: procmail(1), perl(1)
=for openssl foreign manuals: procmail(1), perl(1)
=over 2

2
doc/man1/tsget.pod
View File

@ -185,7 +185,7 @@ example:
=head1 SEE ALSO
=for comment foreign manuals: WWW::Curl::Easy
=for openssl foreign manuals: WWW::Curl::Easy
L<openssl(1)>,
L<openssl-ts(1)>,

2
doc/man3/BIO_f_base64.pod
View File

@ -6,7 +6,7 @@ BIO_f_base64 - base64 BIO filter
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/bio.h>
#include <openssl/evp.h>

2
doc/man3/BIO_f_cipher.pod
View File

@ -6,7 +6,7 @@ BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/bio.h>
#include <openssl/evp.h>

2
doc/man3/BIO_f_md.pod
View File

@ -6,7 +6,7 @@ BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/bio.h>
#include <openssl/evp.h>

2
doc/man3/BIO_f_ssl.pod
View File

@ -11,7 +11,7 @@ BIO_ssl_shutdown - SSL BIO
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/bio.h>
#include <openssl/ssl.h>

2
doc/man3/BIO_get_ex_new_index.pod
View File

@ -17,7 +17,7 @@ RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/x509.h>

2
doc/man3/DEFINE_STACK_OF.pod
View File

@ -14,7 +14,7 @@ sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/safestack.h>

2
doc/man3/EVP_EncryptInit.pod
View File

@ -65,7 +65,7 @@ EVP_CIPHER_do_all_ex
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>

2
doc/man3/EVP_aes.pod
View File

@ -51,7 +51,7 @@ EVP_aes_256_xts
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>

2
doc/man3/EVP_aria.pod
View File

@ -36,7 +36,7 @@ EVP_aria_256_gcm,
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>

2
doc/man3/EVP_camellia.pod
View File

@ -30,7 +30,7 @@ EVP_camellia_256_ofb
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>

2
doc/man3/EVP_des.pod
View File

@ -28,7 +28,7 @@ EVP_des_ede3_wrap
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>

2
doc/man3/OPENSSL_LH_COMPFUNC.pod
View File

@ -12,7 +12,7 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/lhash.h>

2
doc/man3/OSSL_PARAM_int.pod
View File

@ -32,7 +32,7 @@ OSSL_PARAM_set_octet_ptr
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/params.h>

2
doc/man3/OSSL_trace_enabled.pod
View File

@ -12,7 +12,7 @@ OSSL_TRACE_ENABLED
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/trace.h>

2
doc/man3/OSSL_trace_set_channel.pod
View File

@ -1,6 +1,6 @@
=pod
=for comment foreign manuals: atexit(3)
=for openssl foreign manuals: atexit(3)
=head1 NAME

2
doc/man3/PEM_read_CMS.pod
View File

@ -40,7 +40,7 @@ PEM_write_bio_SSL_SESSION
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/pem.h>

2
doc/man3/SSL_get_all_async_fds.pod
View File

@ -9,7 +9,7 @@ SSL_get_changed_async_fds
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/async.h>
#include <openssl/ssl.h>

2
doc/man3/SSL_set_async_callback.pod
View File

@ -12,7 +12,7 @@ SSL_async_callback_fn
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/ssl.h>

2
doc/man3/X509_dup.pod
View File

@ -287,7 +287,7 @@ X509_dup,
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/asn1t.h>

2
doc/man3/d2i_X509.pod
View File

@ -387,7 +387,7 @@ i2d_X509_VAL,
=head1 SYNOPSIS
=for comment generic
=for openssl generic
TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);
TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);

2
doc/man7/bio.pod
View File

@ -6,7 +6,7 @@ bio - Basic I/O abstraction
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/bio.h>

2
doc/man7/ossl_store-file.pod
View File

@ -14,7 +14,7 @@ ossl_store-file - The store 'file' scheme loader
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/store.h>

2
doc/man7/ossl_store.pod
View File

@ -6,7 +6,7 @@ ossl_store - Store retrieval functions
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/store.h>

2
doc/man7/provider-cipher.pod
View File

@ -6,7 +6,7 @@ provider-cipher - The cipher library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>

2
doc/man7/provider-digest.pod
View File

@ -6,7 +6,7 @@ provider-digest - The digest library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>

2
doc/man7/provider-keyexch.pod
View File

@ -6,7 +6,7 @@ provider-keyexch - The keyexch library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>

2
doc/man7/provider-mac.pod
View File

@ -6,7 +6,7 @@ provider-mac - The mac library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>

2
doc/man7/provider-signature.pod
View File

@ -6,7 +6,7 @@ provider-signature - The signature library E<lt>-E<gt> provider functions
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>

10
doc/man7/provider.pod
View File

@ -6,7 +6,7 @@ provider - OpenSSL operation implementation providers
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/provider.h>
@ -123,8 +123,6 @@ The number for this operation is B<OSSL_OP_CIPHER>.
The functions the provider can offer are described in
L<provider-cipher(7)>
=begin comment NOT AVAILABLE YET
=item Message Authentication Code (MAC)
In the OpenSSL libraries, the corresponding method object is
@ -133,10 +131,6 @@ The number for this operation is B<OSSL_OP_MAC>.
The functions the provider can offer are described in
L<provider-mac(7)>
=end comment
=begin comment NOT AVAILABLE YET
=item Key Derivation Function (KDF)
In the OpenSSL libraries, the corresponding method object is
@ -145,8 +139,6 @@ The number for this operation is B<OSSL_OP_KDF>.
The functions the provider can offer are described in
L<provider-kdf(7)>
=end comment
=item Key Exchange
In the OpenSSL libraries, the corresponding method object is

4
util/find-doc-nits
View File

@ -444,7 +444,7 @@ sub check {
check_section_location($id, $contents, "EXAMPLES", "SEE ALSO");
}
unless ( $contents =~ /=for comment generic/ ) {
unless ( $contents =~ /=for openssl generic/ ) {
if ( $filename =~ m|man3/| ) {
name_synopsis($id, $filename, $contents);
functionname_check($id, $filename, $contents);
@ -482,7 +482,7 @@ sub check {
err($id, "Possible version style issue")
if $contents =~ /OpenSSL version [019]/;
if ( $contents !~ /=for comment multiple includes/ ) {
if ( $contents !~ /=for openssl multiple includes/ ) {
# Look for multiple consecutive openssl #include lines
# (non-consecutive lines are okay; see man3/MD5.pod).
if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) {