[Security] [WIP] Add documentation for the Security Component

[matthiasnoback]

This is a work in progress - I am writing documentation for the Security Component.

My goals:

• Describe the component "as stand-alone as possible", so no assumptions are being made about the framework used (like the Symfony framework, using the SecurityBundle, or the Silex micro-framework, using the SecurityServiceProvider).
• Write (in general) about the available classes and relevant interfaces inside the component.
• Show ways of extending the component's behavior.
• Give a more detailed overview of the authentication and authorization process, so users may better understand what's happening (aside from knowing how to configure it in a Symfony app, the Book describes this very well).

Though the documentation is still in a very early stage, I already send this pull request, so everyone knows I'm working on it (and maybe there are some people who would like to collaborate, since this appears to be quite an undertaking...).

Any suggestions are welcome by the way!

[wouterj]

This should be:

/**
 * @var SecurityContextInterface
 */

As well as the other examples

[matthiasnoback]

@wouterj Thanks for your feedback! Do you have a reference page for the commenting style? I could probably do this right the first time ;)

[wouterj]

@matthiasnoback The documentation standards are just merged in the documentation. You can read it here: https://github.com/symfony/symfony-docs/blob/master/contributing/documentation/overview.rst#standards (it doesn't appear at the symfony website...)

[weaverryan]

I guess SecurityContextInterface would be even better :)

[matthiasnoback]

I have made the necessary changes based on all of the above comments, and also added the third part of the docs, about authorization. Still a work in progress, any comments are very welcome...

[stof]

you should use :: at the end of the previous paragraph instead

[wouterj]

Don't use the :: shorthand if you don't want to put a : after the sentence, use the .. code-block:: php instead. The :: will be replaced with : and the indented text after it will be seen as code.

[wouterj]

You haven't understood the :: rule. If you have something like this:

 Every controller needs to return a ``Request``:

 .. code-block:: php

     return new Request(...);

You should use:

Every controller needs to return a ``Request``::

    return new Request(...);

This is equal on the screen, the :: part will be replaced by a single : and the indented text below the :: is seen as a PHP code block.

You should use the normal code-block syntax in every other situation. I have marked some, but fix the others as well.

[matthiasnoback]

I have been thinking about this pull request: it is time to merge and close for now. I have been struggling with the still missing ACL part, and especially with the question how I could add anything interesting complementary to what can be found about ACL in the relevant Cookbook articles. Also, what I have been written can be (and has proven to be) useful for Symfony users, so I will finish my work this week. Let this get out in the open (so others may contribute to it).

[weaverryan]

@matthiasnoback big +1! Additional details and updates can be added later, as soon as we merge, people will start to add and correct things, which is awesome!

As far as ACL, probably the cookbook would need to eventually be moved into a secondary component doc in the security section (I don't think it really has anything to do with the framework). But, that can come later.

Ping back when you've rebased and done your final work. Thanks for taking this on!

[matthiasnoback]

Thanks, Ryan. Well, this is it then. I've rebased my branch and it should be ready to be merged (all feedback has been taken into account).
As a closing note: it has been quite a journey, reading through all the code, trying to figure it all out. I've learned a lot about writing docs, and about finding little ways of extending/modifying the behavior of this "complex, not complicated" component. Thanks for your reviews and suggestions.

[wouterj]

This should be:

    $this->providerKey
);

[wouterj]

Great job @matthiasnoback! I have done a last check and found some errors. I prefer to add the long roles (:class:, :method:) on new lines if it crosses the 80th character, it isn't needed but looks better.

[matthiasnoback]

Thanks you too @wouterj! I also prefer shorter lines, but changing them all to comply with the 80 characters rule is too much I think: many times these :class: and :method: references take more than a single line by themselves. So I would suggest leaving them as they are, for now.