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

#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


Messages In This Thread
Documentation improvements - by RobertSF - 11-09-2014, 05:45 PM
RE: Documentation improvements - by RobertSF - 11-11-2014, 11:54 AM
RE: Documentation improvements - by Chroma - 11-14-2014, 09:30 AM
RE: Documentation improvements - by Narf - 11-17-2014, 04:41 AM
RE: Documentation improvements - by RobertSF - 11-17-2014, 03:21 PM
RE: Documentation improvements - by Narf - 11-18-2014, 02:36 AM
RE: Documentation improvements - by includebeer - 11-17-2014, 07:01 PM
RE: Documentation improvements - by RobertSF - 11-17-2014, 07:03 PM
RE: Documentation improvements - by includebeer - 11-17-2014, 08:28 PM
RE: Documentation improvements - by twpmarketing - 11-18-2014, 03:13 PM
RE: Documentation improvements - by slax0r - 11-18-2014, 01:11 AM
RE: Documentation improvements - by sv3tli0 - 11-18-2014, 03:20 AM
RE: Documentation improvements - by jlp - 12-31-2014, 04:28 PM
RE: Documentation improvements - by RobertSF - 12-31-2014, 05:25 PM

Digg   Delicious   Reddit   Facebook   Twitter   StumbleUpon  


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