• 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Documentation could be more newbie-friendly

#1
Hi,

I've used CodeIgniter in the past (version 2.1.3) and have recently started a project in CI 4 (4.11).
I really like it and it allows me code much cleaner.

But the documentation could use a bit more examples for people who are new to CI 4 (and new to PHP 7 and namespaces, if I'm honest).
For example, when I tried to configure the encryption key for the Encryption Library, it took me a while to understand that where it said :


PHP Code:
// $key will be assigned a 32-byte (256-bit) random key
$key Encryption::createKey(); 

it should actually have said :

PHP Code:
// $key will be assigned a 32-byte (256-bit) random key
$key = \CodeIgniter\Encryption\Encryption::createKey(); 

When I did what the documentation said, I got an error saying PHP couldn't find the Encryption class. It only worked when I fully typed out the namespaced class name.
So in the strictest sense, the documentation is wrong, or at least incomplete.

The above is just one example of several situations I've encountered so far, where I needed to do some guessing and trial-and-error to get the (incomplete) examples in the documentations to actually work.

Still, overall the documentation is pretty good.

Thanks,
Fluffy
Reply

#2
(02-21-2021, 08:12 AM)Fluffy Wrote: But the documentation could use a bit more examples for people who are new to CI 4 (and new to PHP 7 and namespaces, if I'm honest).
For example, when I tried to configure the encryption key for the Encryption Library, it took me a while to understand that where it said :

PHP Code:
// $key will be assigned a 32-byte (256-bit) random key
$key Encryption::createKey(); 

it should actually have said :

PHP Code:
// $key will be assigned a 32-byte (256-bit) random key
$key = \CodeIgniter\Encryption\Encryption::createKey(); 

When I did what the documentation said, I got an error saying PHP couldn't find the Encryption class. It only worked when I fully typed out the namespaced class name.
So in the strictest sense, the documentation is wrong, or at least incomplete.
Yes, you are correct. I will fix it.

I send PR.
https://github.com/codeigniter4/CodeIgniter4/pull/4320

(02-21-2021, 08:12 AM)Fluffy Wrote: The above is just one example of several situations I've encountered so far, where I needed to do some guessing and trial-and-error to get the (incomplete) examples in the documentations to actually work.
If you know another place where has code that does not work,
feel free to point it out.
Reply

#3
Hi kenjis,

Thanks for your reply and for the pull request.
I'll add other similar issues to this thread if I run into them.

Kind regards,
Fluffy
Reply

#4
I found another thing that is a bit unclear in the documentation.
When using the "is_unique" validation rule in a Model, you apparently have to supply the table and field name that you want to be unique.

I assumed it to be obvious that the field you want to be checked for uniqueness is the field that you define the rule for ?
So the rule resulted in an error (about a null value being supplied to the is_unique() method as the 2nd argument), when I didn't supply <table>.<field>.

There may be good reasons to require explicitly stating <table>.<field>, but it would help if the documentation said so.
Reply

#5
Another remark about the docs.
I keep them in separate posts, for clarity.

Why is there no separate section about using forms ?
Many applications use forms to allow users to enter information.

It would be nice to have this under "General Topics", even if it just points you to the form helper and the "Building Your First Application" section for an example.
Reply

#6
(03-06-2021, 04:56 AM)Fluffy Wrote: I found another thing that is a bit unclear in the documentation.
When using the "is_unique" validation rule in a Model, you apparently have to supply the table and field name that you want to be unique.

I assumed it to be obvious that the field you want to be checked for uniqueness is the field that you define the rule for ?
So the rule resulted in an error (about a null value being supplied to the is_unique() method as the 2nd argument), when I didn't supply <table>.<field>.

There may be good reasons to require explicitly stating <table>.<field>, but it would help if the documentation said so.

Where should it be documented?
Reply

#7
Please also check the description of **countAll()** and **countAllResults()**. Usage of both are documented as identical, which I think isn't the case:

https://codeigniter.com/user_guide/datab...lpers.html
Reply

#8
(03-22-2021, 10:11 PM)bastian Wrote: Please also check the description of **countAll()** and **countAllResults()**. Usage of both are documented as identical, which I think isn't the case:

https://codeigniter.com/user_guide/datab...lpers.html
I sent PR: https://github.com/codeigniter4/CodeIgniter4/pull/4472
Reply


Digg   Delicious   Reddit   Facebook   Twitter   StumbleUpon  


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