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

#1
Is it possible to enhance the user documentation by providing datatypes to method signatures? It's easier to see everything in a glance that you don't need to find what and where things are.

See examples from:
Java http://icecream.me/5bd24c8336499692e990a7de84e4e8ba
PHP http://icecream.me/44998e053b59b2bbf505c86ded89afee
.NET framework http://icecream.me/26cfe49c08b2285ff859b5e99bf60369

and so forth.
Long live CodeIgniter!
Reply

#2
(08-07-2016, 10:34 PM)prezire Wrote: Is it possible to enhance the user documentation by providing datatypes to method signatures? It's easier to see everything in a glance that you don't need to find what and where things are.

See examples from:
Java http://icecream.me/5bd24c8336499692e990a7de84e4e8ba
PHP http://icecream.me/44998e053b59b2bbf505c86ded89afee
.NET framework http://icecream.me/26cfe49c08b2285ff859b5e99bf60369

and so forth.

Unlike Java (and not sure about .NET), PHP functions don't necessarily return a declared datatype. Take stripos for example:

http://php.net/manual/en/function.stripos.php

In CI, this happens a lot. Consider the Input class methods for getting values from GET or POST vars. Maybe it could help the docs to know what the return type is, but if you've really read the entire user guide, do you really still need that?
Reply

#3
(08-07-2016, 10:58 PM)skunkbad Wrote:
(08-07-2016, 10:34 PM)prezire Wrote: Is it possible to enhance the user documentation by providing datatypes to method signatures? It's easier to see everything in a glance that you don't need to find what and where things are.

See examples from:
Java http://icecream.me/5bd24c8336499692e990a7de84e4e8ba
PHP http://icecream.me/44998e053b59b2bbf505c86ded89afee
.NET framework http://icecream.me/26cfe49c08b2285ff859b5e99bf60369

and so forth.

Unlike Java (and not sure about .NET), PHP functions don't necessarily return a declared datatype. Take stripos for example:

http://php.net/manual/en/function.stripos.php

In CI, this happens a lot. Consider the Input class methods for getting values from GET or POST vars. Maybe it could help the docs to know what the return type is, but if you've really read the entire user guide, do you really still need that?

IMO yes, it's better to have it especially when you're on tight deadlines wherein you only need to get a single glance of what the signatures looks like. It doesn't have to be declared datatypes because native datatypes will do as long as the signatures are there.

See this screenshot http://icecream.me/5cf61b1fd05c152a3433c06c77e0b246.
To the right, are the helper functions. To the left is their equivalent user guide. I've modified singular() with datatypes in it VS plural(). Can you see the difference and ease of quickly knowing what the method signatures are? This is the end result http://icecream.me/c7a8c6831cfb34ebde128c797e59a283.
Long live CodeIgniter!
Reply

#4
Do you not see the dedicated "Return type" line?
Reply

#5
(08-08-2016, 04:09 AM)Narf Wrote: Do you not see the dedicated "Return type" line?

I do. It's not good to look at with all the mess it has http://icecream.me/8633fd13e24b9d203af3dfceb057c4ee.
Long live CodeIgniter!
Reply

#6
(08-08-2016, 05:30 AM)prezire Wrote:
(08-08-2016, 04:09 AM)Narf Wrote: Do you not see the dedicated "Return type" line?

I do. It's not good to look at with all the mess it has http://icecream.me/8633fd13e24b9d203af3dfceb057c4ee.

I don't see a mess.

Seriously, this is one of the most pretentious complaints I've seen in a long time.
Reply

#7
(08-09-2016, 04:07 AM)Narf Wrote:
(08-08-2016, 05:30 AM)prezire Wrote:
(08-08-2016, 04:09 AM)Narf Wrote: Do you not see the dedicated "Return type" line?

I do. It's not good to look at with all the mess it has http://icecream.me/8633fd13e24b9d203af3dfceb057c4ee.

I don't see a mess.

Seriously, this is one of the most pretentious complaints I've seen in a long time.

It's not pretentious. Seriously, don't say it like that otherwise you'll cause unprofessional commotions. CI3's documentation is the only documentation I know that doesn't have this. Even Ionniezell/kilishan agrees with its benefits http://icecream.me/083b9d8273b54a14038f07796adf3ad7.
Long live CodeIgniter!
Reply

#8
The reference sections in the user guide are dictated by Sphinx, which was intended for python and has an adapter for PHP. We have experimented with other API tools, and decided that the present form is liveable, if not ideal.

@prezire: chill!
Reply

#9
(08-09-2016, 04:09 PM)prezire Wrote:
(08-09-2016, 04:07 AM)Narf Wrote:
(08-08-2016, 05:30 AM)prezire Wrote:
(08-08-2016, 04:09 AM)Narf Wrote: Do you not see the dedicated "Return type" line?

I do. It's not good to look at with all the mess it has http://icecream.me/8633fd13e24b9d203af3dfceb057c4ee.

I don't see a mess.

Seriously, this is one of the most pretentious complaints I've seen in a long time.

It's not pretentious. Seriously, don't say it like that otherwise you'll cause unprofessional commotions. CI3's documentation is the only documentation I know that doesn't have this. Even Ionniezell/kilishan agrees with its benefits http://icecream.me/083b9d8273b54a14038f07796adf3ad7.

So, you're entitled to saying whatever you want, but if I reply back in the same manner, it's unprofessional?

You've proposed something that would require non-insignificant effort, without mentioning that it already exists in a different form, but when that's pointed out all you have to say is "not good to look at". Giving zero supporting points in favor of what you want ("others do it" is a well-known fallacy, not a meaningful argument) and zero evidence to support your claim that what we have is not good.
How is that not pretentious? You're literally providing nothing but your own preference.

Here's a real, factually-relevant argument:

Including the return type in the signature itself, would imply that the return type in question is actually declared as such in the framework code, like it is indeed the case with CI4-dev documentation - this condition can obviously never be true in CI3.
Reply

#10
(08-10-2016, 02:14 AM)Narf Wrote:
(08-09-2016, 04:09 PM)prezire Wrote:
(08-09-2016, 04:07 AM)Narf Wrote:
(08-08-2016, 05:30 AM)prezire Wrote:
(08-08-2016, 04:09 AM)Narf Wrote: Do you not see the dedicated "Return type" line?

I do. It's not good to look at with all the mess it has http://icecream.me/8633fd13e24b9d203af3dfceb057c4ee.

I don't see a mess.

Seriously, this is one of the most pretentious complaints I've seen in a long time.

It's not pretentious. Seriously, don't say it like that otherwise you'll cause unprofessional commotions. CI3's documentation is the only documentation I know that doesn't have this. Even Ionniezell/kilishan agrees with its benefits http://icecream.me/083b9d8273b54a14038f07796adf3ad7.

So, you're entitled to saying whatever you want, but if I reply back in the same manner, it's unprofessional?

You've proposed something that would require non-insignificant effort, without mentioning that it already exists in a different form, but when that's pointed out all you have to say is "not good to look at". Giving zero supporting points in favor of what you want ("others do it" is a well-known fallacy, not a meaningful argument) and zero evidence to support your claim that what we have is not good.
How is that not pretentious? You're literally providing nothing but your own preference.

Here's a real, factually-relevant argument:

Including the return type in the signature itself, would imply that the return type in question is actually declared as such in the framework code, like it is indeed the case with CI4-dev documentation - this condition can obviously never be true in CI3.

We are entitled to everything we say in this forum however, there was literally none, nothing whatsoever and never any intention of giving pretentious suggestions, not even in any insignificant manner like you've mentioned. So yes, your answer was very unprofessional. You can't tell any user in this forum, may he be a junior or senior member, as pretentious, or giving out pretentious complaints like Internet trolls as you've slightly implied, especially when we're here to contribute for the betterment of the CI framework as a whole.

I did mention it's not good to look at and I meant what I said. I did not spend time on those included screenshots for something insignificant. I'm always in the fast lane of deadlines and the current documentation format, does indeed look messy, especially when doing quick glances. I was a designer before I became a programmer and I can tell you in an expert, artistic manner, the formatting is messy. The reason may be relative to me personally however, if it seem fine to you, I can tell you, it is then, also a relatively pretentious claim on your end.

Most modern, strict data-typed frameworks contain the same format I proposed. So how does that make it not a meaningful argument? And for the record, you misunderstood this thread's entire point with your last answer. Clearly this topic is about CI4 documentation. What I proposed was purposefully for CI4 and NOT CI3! That is the reason why this proposal was made --CI3 has no datatypes while CI4 does. If CI4 has data types, then why not provide additional information by including data-types in every method signature lines?

But no matter. I have reverted my code commits as discussed with Ionniezell/kilishan since there aren't any final words on this proposal yet.
Long live CodeIgniter!
Reply


Digg   Delicious   Reddit   Facebook   Twitter   StumbleUpon  


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