Readme Select: Cols vs Set functionality is unclear

[jakeasmith]

From this example its not obvious that set() is its own key-value pair unrelated to cols() and bind*(). Consider splitting set() into its own example.

$insert
    ->into('foo')                   // INTO this table
    ->cols([                        // insert these as "(col) VALUES (:col)"
        'bar',
        'baz',
    ])
    ->set('id', 'NULL')             // insert raw values for this column
    ->bindValue('foo', 'foo_val')   // bind one value to a placeholder
    ->bindValues([                  // bind these values
        'bar' => 'foo',
        'baz' => 'zim',
    ]);

[harikt]

@jakeasmith would love to get a PR. Thanks.

[jakeasmith]

I don't have time right now, but I wanted to at least open up the issue here. Its tripped my team up more than once.

[harikt]

@jakeasmith sure. I just mentioned.
Someone can work on when we have time.
Thank you

[harikt]

@jakeasmith I am not sure whether moving to set will help.

[pmjones]

I just modified the read me very slightly. Let me know if that helps.

Regarding the phrase "its not obvious that set() is its own key-value pair unrelated to cols() and bind*()" -- I don't think it's unrelated. The set() method is a raw connection to the column/value pairs. You could mimic cols()+bind() by calling set() multiple times and passing your own values.

[jeremyjannotta]

I think the biggest thing that wasn't clear to me, was that you can use set() OR cols() OR both, partly because the example shows them used all together. So showing them in separate examples is one way that could help explain the usage.

[pmjones]

/me nods

I'm not sure how to write that up -- if you could send a PR that would help a great deal.

[pmjones]

Guys, I'm sorry, I don't know how to write this up any better. If you can send a PR with better examples I'll be happy to review it. In the mean time, I'm closing this issue; I can reopen it or reference it later as needed.

[harikt]

may be we close it once they feel it is addressed ? I know our release script probably won't allow for it :( .