@@ -39,8 +39,14 @@ are marked with an ``@api`` tag in their source code. For example::
3939 interface HttpKernelInterface
4040 {
4141
42- When using these interfaces, we guarantee full backwards compatibility for the
43- following use cases:
42+ In simple words, the difference between regular and API interfaces is that you
43+ can implement API interfaces yourself and we will guarantee full backwards
44+ compatibility. The same is not true for regular interfaces: We may, for example,
45+ add an optional parameter or a new method to them and thus break your own
46+ implementation.
47+
48+ In detail, we guarantee full backwards compatibility for the following use
49+ cases:
4450
4551============================================== ============== ==============
4652Use Case Regular API
@@ -80,8 +86,13 @@ Like API interfaces, API classes are marked with an ``@api`` tag::
8086 class Request
8187 {
8288
83- When using these classes, we guarantee full backwards compatibility for the
84- following use cases:
89+ The difference between regular and API classes is that we guarantee full
90+ backwards compatibility if you extend an API class and override its methods,
91+ but not for regular classes. In regular classes, we may for example add an
92+ optional parameter to a method and thus break your overridden method.
93+
94+ Again, here are the details about which use cases we guarantee full backwards
95+ compatibility for:
8596
8697============================================== ============== ==============
8798Use Case Regular API