skeleton of permission doc

API-Permissions.md

@@ -0,0 +1,16 @@
+# API Permissions
+
+The ReCodEx API features a custom system for flexible definition of access 
+control rules. Its configuration is loosely based on `Nette\Security`, but it 
+brings many additional features, such as an IDE-friendly code interface and 
+declarative configuration using the NEON language.
+
+## Setup and Usage
+
+Compiler extension, config.neon, permissions.neon, interfaces and DI.
+
+## Extending the ACL
+
+### Custom ACL Interfaces
+
+### Custom Assertions

Implementation.md

@@ -684,22 +684,17 @@ In a system storing user data has to be implemented some kind of permission
 checking. Each user has a role, which corresponds to his/her privileges.
 Our research showed, that three roles are sufficient -- student, supervisor
 and administrator. The user role has to be
-checked with every request. The good points is, that roles nicely match with
+checked with every request. The good point is, that roles nicely match with
 granularity of API endpoints, so the permission checking can be done at the
-beginning of each request. That is implemented using PHP annotations, which
-allows to specify allowed user roles for each request with very little of code,
-but all the business logic is the same, together in one place.
-
-However, roles cannot cover all cases. For example, if user is a supervisor, it
-relates only to groups, where he/she is a supervisor. But using only roles
-allows him/her to act as supervisor in all groups in the system. Unfortunately,
-this cannot be easily fixed using some annotations, because there are many
-different cases when this problem occurs. To fix that, some additional checks
-can be performed at the beginning of request processing. Usually it is only one
-or two simple conditions.
-
-With this two concepts together it is possible to easily cover all cases of
-permission checking with quite a small amount of code.
+beginning of each request. 
+
+The problem of checking permissions is however more complicated than a simple
+comparison of user roles: some roles rank higher than others and
+some resources can be accessed under more complicated conditions - for example,
+students should be only able to join public groups.
+
+To overcome these problems, we designed a complex ACL system described on the
+[API Permissions](API-Permissions) page.
 
 ### Uploading Files