php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Bug #44885 grouped optional args is no longer supported
Submitted: 2008-05-01 21:41 UTC Modified: 2008-05-02 09:27 UTC
From: colder@php.net Assigned:
Status: Not a bug Package: Doc Build problem
PHP Version: Irrelevant OS: Irrelevant
Private report: No CVE-ID: None
Welcome back! If you're the original bug submitter, here's where you can edit the bug or add additional notes.
If this is not your bug, you can add a comment by following this link.
If this is your bug, but you forgot your password, you can retrieve your password here.
Password:
Status:
Package:
Bug Type:
Summary:
From: colder@php.net
New email:
PHP Version: OS:

 

 [2008-05-01 21:41 UTC] colder@php.net
Description:
------------
php.net/rand

The proto is : rand([min, max]); 
xml is :
<methodparam choice="opt"><type>int</type><parameter>min</parameter></methodparam>
    <methodparam><type>int</type><parameter>max</parameter></methodparam>

With PhD, it ends up being: int rand  ([ int $min  ], int $max  )

So, either 
1) the renderer don't handle groups of optional args anymore, or
2) there is a new syntax to group optional args together and the xml should be fixed.


Regards


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2008-05-01 23:27 UTC] cellog@php.net
correct is:

<methodparam
choice="opt"><type>int</type><parameter>min</parameter></methodparam>
   
<methodparam choice="opt"><type>int</type><parameter>max</parameter></methodparam>
 [2008-05-01 23:53 UTC] colder@php.net
title made no sense
 [2008-05-01 23:54 UTC] colder@php.net
Well no, that will make it rand([min[, max]]), which is also wrong, it's rand([min, max]) as in either the two or none.
 [2008-05-01 23:54 UTC] philip@php.net
The trouble with that is this:

int rand  ([ int $min  [, int $max  ]] )

versus this:

int rand  ([ int $min , int $max  ] )

and rand() follows the latter because it requires either 0 or 2 arguments and not 1. PhD creates the first if choice="opt" is used twice.

So basically we need a syntax for each and it appears both our dsssl and xsl based build systems treated this differently. The BC approach would add the following to PhD:

if (only the first arg is optional) {
  make them all optional together;
}

But it's a strange syntax and ideally we'd come up with some better markup.


 [2008-05-02 07:28 UTC] bjori@php.net
> if (only the first arg is optional) {
>   make them all optional together;
> }

That will break bunch of array_*() argument listing were the optional parameter is the 3rd of 5.
This was an error in the XSL which was fixed in PhD.

The markup for rand() is simply wrong. This function can be used in two different ways, either by passing no parameters or two.
The correct way to do this is having two methodsynopsis, one that takes no arguments and another one that takes two (requiered) arguments.

-Hannes

 [2008-05-02 09:27 UTC] rquadling@php.net
Docbook doesn't have a methodparamgroup like tag (made up name). 

If it did and the group could be marked choice="opt" and could be nested, then this would work be used.

Another option is to not render the ] as part of the <methodparam> tag.

Instead, accumulate a count for the <methodsynopsis> and render all the ] at the close of </methodsynopsis>

That way every choice="opt" would act as another level of option-ness.

Currently though, as Hannes says, 2 methodsynopsis is the route being used.
 
PHP Copyright © 2001-2020 The PHP Group
All rights reserved.
Last updated: Thu Aug 06 02:01:24 2020 UTC