• 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Documentation improvements

#1
Codeigniter is known for its good documentation, but that doesn't mean it can't be improved. I'd like to suggest a Documentation subforum under Issues, where we can point out errors and suggest improvements. I think this is important, especially considering that many people starting with Codeigniter are also new to PHP.

Here is a concrete example. The documentation states under the section Callbacks: Your own Validation Functions,

Quote:To invoke a callback just put the function name in a rule, with "callback_" as the rule prefix. If you need to receive an extra parameter in your callback function, just add it normally after the function name between square brackets, as in: "callback_foo[bar]", then it will be passed as the second argument of your callback function.

The above is not incorrect but it can lead novice programmers to tear their hair out. The problem is that the example shows how to pass the string 'bar' to the callback function, yet the more common case would be passing the value in a variable. And to pass the value of variable $bar, the example should read "callback_foo[$bar]" while reminding the reader that double-quotes must be used if PHP is to parse $bar as a variable. The documentation could further clarify,

Quote:To pass the value of a variable, you must use concatenation, double quotes, or complex syntax. Like this:
concatenation: 'callback_foo['. $bar . ']'
double quotes: "callback_foo[$bar]"
complex syntax: "callback_foo[{$bar['snafu']}]"
That last style is especially helpful when passing array elements.

The documentation could also link to the PHP manual, specifically to:
Strings - Variable Parsing, and Why is $foo[bar] wrong?.

You can quibble with the example I'm giving, but I still think we can make a community effort to improve the manual. What do you think?
Reply

#2
In the section explaining $this->input->post(), it would be helpful if the documentation noted that array elements cannot be retrieved individually.

This comes up when you use an array in your forms. If you use $book['isbn'], $book['author'], $book['title'], $book['price'] in your form, for example, upon posting the form, the $_POST array will contain an array called book with keys isbn, author, title, and price. You can retrieve those one by one directly by accessing the $_POST variable, like this:
PHP Code:
$price $_POST['book']['price']; 

But using the Post method of the Input class, you must get the whole array and then access the individual elements, like this:
PHP Code:
$book $this->input->post('book');
$price $book['price']; 
Reply

#3
That would make a nice addition to the docs.
Reply

#4
(11-09-2014, 05:45 PM)RobertSF Wrote: Codeigniter is known for its good documentation, but that doesn't mean it can't be improved. I'd like to suggest a Documentation subforum under Issues, where we can point out errors and suggest improvements. I think this is important, especially considering that many people starting with Codeigniter are also new to PHP.

Here is a concrete example. The documentation states under the section Callbacks: Your own Validation Functions,



Quote:To invoke a callback just put the function name in a rule, with "callback_" as the rule prefix. If you need to receive an extra parameter in your callback function, just add it normally after the function name between square brackets, as in: "callback_foo[bar]", then it will be passed as the second argument of your callback function.

The above is not incorrect but it can lead novice programmers to tear their hair out. The problem is that the example shows how to pass the string 'bar' to the callback function, yet the more common case would be passing the value in a variable. And to pass the value of variable $bar, the example should read "callback_foo[$bar]" while reminding the reader that double-quotes must be used if PHP is to parse $bar as a variable. The documentation could further clarify,



Quote:To pass the value of a variable, you must use concatenation, double quotes, or complex syntax. Like this:
concatenation: 'callback_foo['. $bar . ']'
double quotes: "callback_foo[$bar]"
complex syntax: "callback_foo[{$bar['snafu']}]"
That last style is especially helpful when passing array elements.

The documentation could also link to the PHP manual, specifically to:
Strings - Variable Parsing, and Why is $foo[bar] wrong?.

You can quibble with the example I'm giving, but I still think we can make a community effort to improve the manual. What do you think?

It's the CodeIgniter user guide, not the PHP manual. It's not supposed to teach you what the difference between single and double quotes is.

(11-11-2014, 11:54 AM)RobertSF Wrote: In the section explaining $this->input->post(), it would be helpful if the documentation noted that array elements cannot be retrieved individually.

This comes up when you use an array in your forms. If you use $book['isbn'], $book['author'], $book['title'], $book['price'] in your form, for example, upon posting the form, the $_POST array will contain an array called book with keys isbn, author, title, and price. You can retrieve those one by one directly by accessing the $_POST variable, like this:


PHP Code:
$price $_POST['book']['price']; 

But using the Post method of the Input class, you must get the whole array and then access the individual elements, like this:


PHP Code:
$book $this->input->post('book');
$price $book['price']; 

This is one of the new features in CI 3.0:


PHP Code:
$price $this->input->post('book[price]'); 
Reply

#5
(11-17-2014, 04:41 AM)Narf Wrote: It's the CodeIgniter user guide, not the PHP manual. It's not supposed to teach you what the difference between single and double quotes is.

That's true, but like I said, many Codeigniter users are PHP novices as well. What I wrote was not an attack on the documentation, but a suggestion to improve it. Most things can be improved, can't they?  Smile
Reply

#6
I agree with Narf on this one. You're supposed to know PHP. If not, go to php.net, read a tutorial or a book. When I read documentation I want to read the minimum amount of text I need to learn what I need! Maybe we could build a page with links to good resources for beginners.
Reply

#7
(11-17-2014, 07:01 PM)includebeer Wrote: I agree with Narf on this one. You're supposed to know PHP. If not, go to php.net, read a tutorial or a book. When I read documentation I want to read the minimum amount of text I need to learn what I need! Maybe we could build a page with links to good resources for beginners.

Alrighty... do you have suggestions to improve the documentation? It's good, but hardly a Bible.  Shy
Reply

#8
The doc needs more details, like on php.net. It needs a complete description of all parameters, return value and multiple code example for all functions. I'm not familiar with the CI3 doc since I use CI2. Maybe it's more detailed in the CI3 doc. But a lot of time I had to look at the actual CI code to know what are the parameters and return value for a function.
Reply

#9
I would maybe add comments to the docs, in a similar way they do on PHP. I found much help from those comments over the years.
Reply

#10
(11-09-2014, 05:45 PM)RobertSF Wrote: Codeigniter is known for its good documentation, but that doesn't mean it can't be improved. I'd like to suggest a Documentation subforum under Issues, where we can point out errors and suggest improvements. I think this is important, especially considering that many people starting with Codeigniter are also new to PHP.

Here is a concrete example. The documentation states under the section Callbacks: Your own Validation Functions,


Quote:To invoke a callback just put the function name in a rule, with "callback_" as the rule prefix. If you need to receive an extra parameter in your callback function, just add it normally after the function name between square brackets, as in: "callback_foo[bar]", then it will be passed as the second argument of your callback function.

The above is not incorrect but it can lead novice programmers to tear their hair out. The problem is that the example shows how to pass the string 'bar' to the callback function, yet the more common case would be passing the value in a variable. And to pass the value of variable $bar, the example should read "callback_foo[$bar]" while reminding the reader that double-quotes must be used if PHP is to parse $bar as a variable. The documentation could further clarify,


Quote:To pass the value of a variable, you must use concatenation, double quotes, or complex syntax. Like this:
concatenation: 'callback_foo['. $bar . ']'
double quotes: "callback_foo[$bar]"
complex syntax: "callback_foo[{$bar['snafu']}]"
That last style is especially helpful when passing array elements.

The documentation could also link to the PHP manual, specifically to:
Strings - Variable Parsing, and Why is $foo[bar] wrong?.

You can quibble with the example I'm giving, but I still think we can make a community effort to improve the manual. What do you think?

(11-17-2014, 03:21 PM)RobertSF Wrote:
(11-17-2014, 04:41 AM)Narf Wrote: It's the CodeIgniter user guide, not the PHP manual. It's not supposed to teach you what the difference between single and double quotes is.

That's true, but like I said, many Codeigniter users are PHP novices as well. What I wrote was not an attack on the documentation, but a suggestion to improve it. Most things can be improved, can't they?  Smile

I didn't say you were attacking it, but teaching PHP to CI users is not our goal and it must work the other way around.
Reply


Digg   Delicious   Reddit   Facebook   Twitter   StumbleUpon  


  Theme © 2014 iAndrew  
Powered By MyBB, © 2002-2019 MyBB Group.