From c8cb7e6068f247a1ce3fb16dc32aab592208b818 Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Tue, 24 Jul 2018 02:01:34 +0000
Subject: [PATCH] Use the same order in NAME, SYNOPSIS, DESCRIPTION, and RETURN
 VALUES to improve readability and ease of maintenance.

Positive feedback jmc
Detailed suggestion & ok schwarze
---
 lib/libtls/man/tls_ocsp_process_response.3 | 55 +++++++++++-----------
 1 file changed, 28 insertions(+), 27 deletions(-)

diff --git a/lib/libtls/man/tls_ocsp_process_response.3 b/lib/libtls/man/tls_ocsp_process_response.3
index b40e9a02d56..6e3aa4aecc7 100644
--- a/lib/libtls/man/tls_ocsp_process_response.3
+++ b/lib/libtls/man/tls_ocsp_process_response.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: tls_ocsp_process_response.3,v 1.5 2018/07/23 18:30:29 tb Exp $
+.\" $OpenBSD: tls_ocsp_process_response.3,v 1.6 2018/07/24 02:01:34 tb Exp $
 .\"
 .\" Copyright (c) 2016 Bob Beck <beck@openbsd.org>
 .\"
@@ -14,19 +14,19 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 23 2018 $
+.Dd $Mdocdate: July 24 2018 $
 .Dt TLS_OCSP_PROCESS_RESPONSE 3
 .Os
 .Sh NAME
 .Nm tls_ocsp_process_response ,
+.Nm tls_peer_ocsp_url ,
+.Nm tls_peer_ocsp_response_status ,
 .Nm tls_peer_ocsp_cert_status ,
 .Nm tls_peer_ocsp_crl_reason ,
-.Nm tls_peer_ocsp_next_update ,
-.Nm tls_peer_ocsp_response_status ,
 .Nm tls_peer_ocsp_result ,
 .Nm tls_peer_ocsp_revocation_time ,
 .Nm tls_peer_ocsp_this_update ,
-.Nm tls_peer_ocsp_url
+.Nm tls_peer_ocsp_next_update
 .Nd inspect an OCSP response
 .Sh SYNOPSIS
 .In tls.h
@@ -36,22 +36,22 @@
 .Fa "const unsigned char *response"
 .Fa "size_t size"
 .Fc
+.Ft const char *
+.Fn tls_peer_ocsp_url "struct tls *ctx"
+.Ft int
+.Fn tls_peer_ocsp_response_status "struct tls *ctx"
 .Ft int
 .Fn tls_peer_ocsp_cert_status "struct tls *ctx"
 .Ft int
 .Fn tls_peer_ocsp_crl_reason "struct tls *ctx"
-.Ft time_t
-.Fn tls_peer_ocsp_next_update "struct tls *ctx"
-.Ft int
-.Fn tls_peer_ocsp_response_status "struct tls *ctx"
 .Ft const char *
 .Fn tls_peer_ocsp_result "struct tls *ctx"
 .Ft time_t
 .Fn tls_peer_ocsp_revocation_time "struct tls *ctx"
 .Ft time_t
 .Fn tls_peer_ocsp_this_update "struct tls *ctx"
-.Ft const char *
-.Fn tls_peer_ocsp_url "struct tls *ctx"
+.Ft time_t
+.Fn tls_peer_ocsp_next_update "struct tls *ctx"
 .Sh DESCRIPTION
 .Fn tls_ocsp_process_response
 processes a raw OCSP response in
@@ -73,6 +73,9 @@ that was obtained by validating a stapled OCSP response during the handshake,
 or via a previous call to
 .Fn tls_ocsp_process_response .
 .Pp
+.Fn tls_peer_ocsp_response_status
+returns the OCSP response status as per RFC 6960 section 2.3.
+.Pp
 .Fn tls_peer_ocsp_cert_status
 returns the OCSP certificate status code as per RFC 6960 section 2.2.
 .Pp
@@ -80,14 +83,9 @@ returns the OCSP certificate status code as per RFC 6960 section 2.2.
 returns the OCSP certificate revocation reason status code as per RFC 5280
 section 5.3.1.
 .Pp
-.Fn tls_peer_ocsp_next_update
-returns the OCSP next update time.
-.Pp
-.Fn tls_peer_ocsp_response_status
-returns the OCSP response status as per RFC 6960 section 2.3.
-.Pp
 .Fn tls_peer_ocsp_result
-returns a string indicating the OCSP status.
+returns a textual representation of the OCSP status code
+returned by one of the previous three functions.
 If the OCSP response was valid and the certificate was not
 revoked, the string indicates the OCSP certificate status.
 Otherwise, the string indicates
@@ -98,10 +96,20 @@ returns the OCSP revocation time.
 .Pp
 .Fn tls_peer_ocsp_this_update
 returns the OCSP this update time.
+.Pp
+.Fn tls_peer_ocsp_next_update
+returns the OCSP next update time.
 .Sh RETURN VALUES
 .Fn tls_ocsp_process_response
 returns 0 on success or -1 on error.
 .Pp
+.Fn tls_peer_ocsp_url
+and
+.Fn tls_peer_ocsp_result
+return
+.Dv NULL
+on error or an out of memory condition.
+.Pp
 The
 .Fn tls_peer_ocsp_response_status
 function returns one of
@@ -139,18 +147,11 @@ or
 .Dv  TLS_CRL_REASON_AA_COMPROMISE
 on success or -1 on error.
 .Pp
-.Fn tls_peer_ocsp_next_update ,
 .Fn tls_peer_ocsp_revocation_time ,
+.Fn tls_peer_ocsp_this_update ,
 and
-.Fn tls_peer_ocsp_this_update
+.Fn tls_peer_ocsp_next_update
 return a time in epoch-seconds on success or -1 on error.
-.Pp
-.Fn tls_peer_ocsp_result
-and
-.Fn tls_peer_ocsp_url
-return
-.Dv NULL
-on error or an out of memory condition.
 .Sh SEE ALSO
 .Xr tls_client 3 ,
 .Xr tls_config_ocsp_require_stapling 3 ,
-- 
2.20.1