Re: remove 'returns no value' from man pages

[Marc Espie]

On Sat, Mar 12, 2016 at 01:18:18PM -0800, Michael McConville wrote:
> Marc Espie wrote:
> > On Fri, Mar 11, 2016 at 05:18:52PM -0800, Michael McConville wrote:
> > > This is specified only irregularly, and people who don't know what a
> > > void return type means are beyond help anyway.
> > > 
> > > This also adds a sentence specifying that X509_free(3) is NULL-safe, now
> > > that we've removed all NULL-checks for it. I should sweep through and
> > > add the sentence the rest of the NULL-safe LibreSSL *_free() functions
> > > soon.
> > > 
> > > ok?
> > 
> > I would keep the one about rewind, maybe make it even stronger.
> > 
> > Using rewind is icky.   It deliberately hides an error message.
> 
> Sounds good - I'll leave that one and remove the rest. Let me know if
> you have a proposed wording for the additional rewind(3) warning.

You will have to work with jmc, I guess.  
I would probably go

The
.Fn rewind
function returns no value.
Prefer
.Fn fseek ,
which is just as portable, and does not hide errors.
.Pp

Re: remove 'returns no value' from man pages

[Michael McConville]

Marc Espie wrote:
> On Fri, Mar 11, 2016 at 05:18:52PM -0800, Michael McConville wrote:
> > This is specified only irregularly, and people who don't know what a
> > void return type means are beyond help anyway.
> > 
> > This also adds a sentence specifying that X509_free(3) is NULL-safe, now
> > that we've removed all NULL-checks for it. I should sweep through and
> > add the sentence the rest of the NULL-safe LibreSSL *_free() functions
> > soon.
> > 
> > ok?
> 
> I would keep the one about rewind, maybe make it even stronger.
> 
> Using rewind is icky.   It deliberately hides an error message.

Sounds good - I'll leave that one and remove the rest. Let me know if
you have a proposed wording for the additional rewind(3) warning.

Re: remove 'returns no value' from man pages

[Marc Espie]

On Fri, Mar 11, 2016 at 05:18:52PM -0800, Michael McConville wrote:
> This is specified only irregularly, and people who don't know what a
> void return type means are beyond help anyway.
> 
> This also adds a sentence specifying that X509_free(3) is NULL-safe, now
> that we've removed all NULL-checks for it. I should sweep through and
> add the sentence the rest of the NULL-safe LibreSSL *_free() functions
> soon.
> 
> ok?

I would keep the one about rewind, maybe make it even stronger.

Using rewind is icky.   It deliberately hides an error message.

Re: remove 'returns no value' from man pages

[Ingo Schwarze]

Hi Michael,

Michael McConville wrote on Fri, Mar 11, 2016 at 05:18:52PM -0800:

> This is specified only irregularly, and people who don't know what a
> void return type means are beyond help anyway.

I don't feel strongly either way, but i certainly don't object.
Usually shorter with the same information is better, and consistency
is good, so you should probably do this.

Yours,
  Ingo

remove 'returns no value' from man pages

[Michael McConville]

This is specified only irregularly, and people who don't know what a
void return type means are beyond help anyway.

This also adds a sentence specifying that X509_free(3) is NULL-safe, now
that we've removed all NULL-checks for it. I should sweep through and
add the sentence the rest of the NULL-safe LibreSSL *_free() functions
soon.

ok?


Index: lib/libc/stdio/fseek.3
===
RCS file: /cvs/src/lib/libc/stdio/fseek.3,v
retrieving revision 1.16
diff -u -p -r1.16 fseek.3
--- lib/libc/stdio/fseek.3  17 Jul 2013 05:42:11 -  1.16
+++ lib/libc/stdio/fseek.3  12 Mar 2016 01:05:07 -
@@ -139,9 +139,6 @@ On some systems an
 object may be a complex object
 and these routines may be the only way to portably reposition a text stream.
 .Sh RETURN VALUES
-The
-.Fn rewind
-function returns no value.
 Upon successful completion,
 .Fn fgetpos ,
 .Fn fseek ,
Index: lib/libc/stdlib/hcreate.3
===
RCS file: /cvs/src/lib/libc/stdlib/hcreate.3,v
retrieving revision 1.6
diff -u -p -r1.6 hcreate.3
--- lib/libc/stdlib/hcreate.3   28 Jul 2010 09:00:20 -  1.6
+++ lib/libc/stdlib/hcreate.3   12 Mar 2016 01:05:07 -
@@ -159,10 +159,6 @@ Otherwise, a value of 0 is returned and
 .Va errno
 is set to indicate the error.
 .Pp
-The
-.Fn hdestroy
-functions
-returns no value.
 .Pp
 If successful, the
 .Fn hsearch
Index: lib/libc/stdlib/malloc.3
===
RCS file: /cvs/src/lib/libc/stdlib/malloc.3,v
retrieving revision 1.93
diff -u -p -r1.93 malloc.3
--- lib/libc/stdlib/malloc.35 Feb 2016 15:09:09 -   1.93
+++ lib/libc/stdlib/malloc.312 Mar 2016 01:05:07 -
@@ -174,9 +174,6 @@ and set
 to
 .Er ENOMEM .
 .Pp
-The
-.Fn free
-function returns no value.
 .Sh IDIOMS
 Consider
 .Fn calloc
Index: lib/libc/stdlib/qsort.3
===
RCS file: /cvs/src/lib/libc/stdlib/qsort.3,v
retrieving revision 1.18
diff -u -p -r1.18 qsort.3
--- lib/libc/stdlib/qsort.3 29 Jan 2015 01:46:31 -  1.18
+++ lib/libc/stdlib/qsort.3 12 Mar 2016 01:05:07 -
@@ -143,9 +143,6 @@ which is faster than
 .Fn heapsort .
 Memory availability and pre-existing order in the data can make this untrue.
 .Sh RETURN VALUES
-The
-.Fn qsort
-function returns no value.
 .Pp
 .Rv -std heapsort mergesort
 .Sh ERRORS
Index: lib/libc/stdlib/tsearch.3
===
RCS file: /cvs/src/lib/libc/stdlib/tsearch.3,v
retrieving revision 1.19
diff -u -p -r1.19 tsearch.3
--- lib/libc/stdlib/tsearch.3   5 Jun 2013 03:39:23 -   1.19
+++ lib/libc/stdlib/tsearch.3   12 Mar 2016 01:05:07 -
@@ -112,9 +112,6 @@ is
 .Dv NULL
 or the datum cannot be found.
 .Pp
-The
-.Fn twalk
-function returns no value.
 .Sh SEE ALSO
 .Xr bsearch 3 ,
 .Xr lsearch 3
Index: lib/libcrypto/man/ASN1_OBJECT_new.3
===
RCS file: /cvs/src/lib/libcrypto/man/ASN1_OBJECT_new.3,v
retrieving revision 1.2
diff -u -p -r1.2 ASN1_OBJECT_new.3
--- lib/libcrypto/man/ASN1_OBJECT_new.3 9 Sep 2015 21:58:20 -   1.2
+++ lib/libcrypto/man/ASN1_OBJECT_new.3 12 Mar 2016 01:05:07 -
@@ -47,9 +47,6 @@ returns
 and sets an error code that can be obtained by
 .Xr ERR_get_error 3 .
 Otherwise it returns a pointer to the newly allocated structure.
-.Pp
-.Fn ASN1_OBJECT_free
-returns no value.
 .Sh SEE ALSO
 .Xr d2i_ASN1_OBJECT 3 ,
 .Xr ERR_get_error 3 ,
Index: lib/libcrypto/man/BUF_MEM_new.3
===
RCS file: /cvs/src/lib/libcrypto/man/BUF_MEM_new.3,v
retrieving revision 1.2
diff -u -p -r1.2 BUF_MEM_new.3
--- lib/libcrypto/man/BUF_MEM_new.3 22 Sep 2015 08:08:07 -  1.2
+++ lib/libcrypto/man/BUF_MEM_new.3 12 Mar 2016 01:05:07 -
@@ -89,9 +89,6 @@ returns the buffer or
 .Dv NULL
 on error.
 .Pp
-.Fn BUF_MEM_free
-returns no value.
-.Pp
 .Fn BUF_MEM_grow
 returns zero on error or the new size (i.e.
 .Fa len Ns ).
Index: lib/libssl/src/doc/crypto/DH_new.pod
===
RCS file: /cvs/src/lib/libssl/src/doc/crypto/DH_new.pod,v
retrieving revision 1.3
diff -u -p -r1.3 DH_new.pod
--- lib/libssl/src/doc/crypto/DH_new.pod4 May 2014 22:26:33 -   
1.3
+++ lib/libssl/src/doc/crypto/DH_new.pod12 Mar 2016 01:05:07 -
@@ -25,8 +25,6 @@ If the allocation fails, DH_new() return
 can be obtained by L. Otherwise it returns a
 pointer to the newly allocated structure.
 
-DH_free() returns no value.
-
 =head1 SEE ALSO
 
 L, L,
Index: lib/libssl/src/doc/crypto/DH_set_method.pod
===
RCS file: