django-cms
diff --git a/‎AUTHORS
Lines changed: 1 addition & 0 deletions b/‎AUTHORS
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/reference/plugins.rst
Lines changed: 21 additions & 15 deletions b/‎docs/reference/plugins.rst
Lines changed: 21 additions & 15 deletions
@@ -255,6 +255,7 @@ Contributors (based on gitlog, 537 unique authors):
 * Jens Diemer
 * JensDiemer
 * Jeroen Noten
+* Jeroen Peters
 * Jessica Tallon
 * Jimmy Lam
 * Johannes Bornhold
 
@@ -192,12 +192,19 @@ CMSPluginBase Attributes and Methods Reference
 
         Default: ``False``
 
-        Not all plugins are usable in text plugins. If your plugin *is* usable in a text plugin:
+        This attribute controls whether your plugin will be usable (and rendered)
+        in a text plugin. When you edit a text plugin on a page, the plugin will show up in
+        the *CMS Plugins* dropdown and can be configured and inserted. The output will even
+        be previewed in the text editor.
+
+        Of course, not all plugins are usable in text plugins. Therefore the default of this
+        attribute is ``False``. If your plugin *is* usable in a text plugin:
 
         * set this to ``True``
-        * make sure your plugin provides its own :meth:`icon_src`
+        * make sure your plugin provides its own :meth:`icon_alt`, this will be used as a tooltip in
+          the text-editor and comes in handy when you use multiple plugins in your text.
 
-        See also: :attr:`icon_src`, :attr:`icon_alt`.
+        See also: :meth:`icon_alt`, :meth:`icon_src`.
 
 
     **Methods**
@@ -326,18 +333,16 @@ CMSPluginBase Attributes and Methods Reference
 
     ..  method:: icon_alt()
 
-        Although it is optional, authors of "text enabled" plugins should consider
-        overriding this function as well.
+        By default :meth:`icon_alt` will return a string of the form: "[plugin type] -
+        [instance]", but can be modified to return anything you like.
 
         This function accepts the ``instance`` as a parameter and returns a string to be
-        used as the ``alt`` text for the plugin's icon which will appear as a tooltip in
-        most browsers.  This is useful, because if the same plugin is used multiple
-        times within the same text plugin, they will typically all render with the
-        same icon rendering them visually identical to one another. This ``alt`` text and
-        related tooltip will help the operator distinguish one from the others.
+        used as the ``alt`` text for the plugin's preview or icon.
 
-        By default :meth:`icon_alt` will return a string of the form: "[plugin type] -
-        [instance]", but can be modified to return anything you like.
+        Authors of text-enabled plugins should consider overriding this function as
+        it will be rendered as a tooltip in most browser. This is useful, because if
+        the same plugin is used multiple times, this tooltip can provide information about
+        its configuration.
 
         :meth:`icon_alt` takes 1 argument:
 
@@ -348,7 +353,7 @@ CMSPluginBase Attributes and Methods Reference
             def icon_alt(self, instance):
                 return "%s - %s" % (force_text(self.name), force_text(instance))
 
-        See also: :attr:`text_enabled`, :attr:`icon_src`.
+        See also: :attr:`text_enabled`, :meth:`icon_src`.
 
 
     .. method:: icon_src(instance)
@@ -361,6 +366,9 @@ CMSPluginBase Attributes and Methods Reference
         ``True`` to return the path to an icon to display in the text of the text
         plugin.
 
+        Since djangocms-text-ckeditor introduced inline previews of plugins, the icon
+        will not be rendered anymore.
+
         icon_src takes 1 argument:
 
         * ``instance``: The instance of the plugin model
@@ -388,8 +396,6 @@ CMSPluginBase Attributes and Methods Reference
         :class:`django.template.Context`, which will be used as context to render the
         plugin template.
 
-        .. versionadded:: 2.4
-
         By default this method will add ``instance`` and ``placeholder`` to the
         context, which means for simple plugins, there is no need to overwrite this
         method.