bug#17862: 24.3; regexp-opt docstring is incorrect

[npostavs]

immerrr again <immerrr@gmail.com> writes:

> +non-@code{nil}

Should be just non-nil, I believe.

> +    the resulting regexp is surrounded by @samp{\(} and @samp{\)}.
> +
> +Otherwise the resulting regexp is surrounded by @samp{\(?:} and
> +@samp{\)}.

This is not 100% accurate, here is a counterexample:

    (regexp-opt '("a" "b" "c")) ;=> "[abc]"

Not sure how detailed we want to be about this is in the docs though.

>  
>  This simplified definition of @code{regexp-opt} produces a
>  regular expression which is equivalent to the actual value
> -(but not as efficient):
> +(but typically more efficient):

"not as efficient" refers to the output of the simplified definition.

>  
>  @example
>  (defun regexp-opt (strings &optional paren)
> -  (let ((open-paren (if paren "\\(" ""))
> -        (close-paren (if paren "\\)" "")))
> +  (let ((open-paren (make-open-paren paren))
> +        (close-paren (make-close-paren paren)))

I'm not sure that adding these undefined make-{open,close}-paren
functions makes things any clearer.

>  The returned regexp is typically more efficient than the equivalent regexp:
>  
> - (let ((open (if PAREN \"\\\\(\" \"\")) (close (if PAREN \"\\\\)\" \"\")))
> + (let ((open (make-open-paren PAREN)) (close (make-close-paren PAREN)))

Same comment here.