765315 - Mention the data type of 'product' param in POD of Bugzilla::Component->new to avoid misunderstanding

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[Koosha KM]

If you try to instantiate an object of an existing component by passing the hash ref 

{name => 'comp_name', product => 'product_name'} 

to Bugzilla::Component->new instead of an ID, an error will be thrown.

The problem is at line 89:

my @values = ($product->id, $name);

where $product is a string and tries to call `id' method.

This bug has been around for 6 years and it seems nobody has faced it yet!

Comment 1

[Koosha KM]

Attachment: patch - v1

Comment 2

[Koosha KM]

Attachment: patch - v1

Comment 3

[Koosha KM]

I understand! product must be an object. Sorry!

Comment 4

[Frédéric Buclin]

(In reply to Koosha Khajeh Moogahi [:koosha] from comment #3)
> I understand! product must be an object. Sorry!

That's what I was writing when you marked this bug as invalid. :)

Comment 5

[Koosha KM]

But, the misunderstanding was due to the fact that the data type of 'product' param was not mentioned in API docs. As the 'name' param is string, it is reasonable to expect 'product' to be string, too. The data type must be mentioned in the doc just like that of create().

I'm attaching a minor patch addressing this issue.

Comment 6

[Koosha KM]

Attachment: POD modification

Comment 7

[Frédéric Buclin]

(In reply to Koosha Khajeh Moogahi [:koosha] from comment #5)
> But, the misunderstanding was due to the fact that the data type of
> 'product' param was not mentioned in API docs.

The type is mentioned. The description of the method says:

"... a hash with the product object the component belongs to and the component name."

"product object" is explicitly mentioned.

Comment 8

[Frédéric Buclin]

Comment on attachment 633632 [details] [diff] [review]
POD modification

>                        read in. If you pass in a hash with the 'name'
>                        and 'product' keys, then the value of the name
>                        key is the name of a component being in the given
>-                       product.
>+                       product. Note that product must be an object of
>+                       Bugzilla::Product.


I don't like the wording. I would much prefer something like:

"If you pass in a hash, it must contain the following keys:
 - name (string): the name of the component.
 - product (object): the Bugzilla::Product object the component belongs to."

Comment 9

[Koosha KM]

Attachment: POD modification - 2

Comment 10

[Frédéric Buclin]

Comment on attachment 633677 [details] [diff] [review]
POD modification - 2

r=LpSolit

Comment 11

[Koosha KM]

No commit?!

Comment 12

[Frédéric Buclin]

Committing to: bzr+ssh://[e-mail]/bugzilla/trunk/
modified Bugzilla/Component.pm
Committed revision 8265.