AuthenticationService documentation?

1

Is there any reference documentation for the authentication plugin? There is, of course, the tutorial, but that only illustrates one particular way of using the plugin. As an example, the constructor in the tutorial takes an array with two elements:

    $authenticationService = new AuthenticationService([
        'unauthenticatedRedirect' => Router::url('/users/login'),
        'queryParam' => 'redirect',
    ]);

but where is the documentation on what (if any) other parameters can be passed? That’s just one example - I would like to see documentation on all the AuthenticationService methods.

–
Jim

2

Well you are welcome to look into the source because it is very well documented.

But usually the doc covers all the main configuration you can/should/have to use.

One problem I run into with this (and the authorization) plugin is the way how code flows from one class/service/trait to the other (especially with all those interfaces).

My guess would be because of the whole “PSR7” compliance which I guess means “read into the PSR7 definition”

3

One of the first things I learned is “comments lie”. Not that anyone intentionally lies when writing the comments, but if you don’t make the conscious effort to keep comments up-to-date, then they start deviating from what the code does, and eventually are completely out of date.

I do have to admit, though, that so far the comments in this project appear to have been well-maintained.

Which is precisely why documentation is needed :slight_smile:

Thanks for the tip!

–
Jim Hyslop

4

Well the question “What should I add to the documentation” can be quite difficult because what is the base knowledge you expect the user to have? Some could be

  • Are you familliar with cakephp at all?
  • Do you know how PHP namespaces work?
  • What about middlewares?

The next question would be "Who do I want to write a documentation to? Someone who wants to use it (Usage documentation) or someone who wants to go deeper (Developer documentation)

There is so much which could be usefull to someone who wants to use the plugin BUT
It all depends on how (and where) you want to use it.

And at least as far as I have gone through the doc for that plugin it provides basic usage examples where it tells you what you have to add/adjust in a basic CakePHP install to get it running.

But there definitely is no “Developer documentation” on how the plugin was made, on which design patterns it is based on and how the inner workings of the plugin do their stuff.

Just some thoughts of mine, no offense :sweat_smile:

5

I’m not at all clear on why you seem to think that this applies to user-maintained comments, but not user-maintained documentation…

6

That’s a very good point!