Merge pull request #870 from nep/patch-14

Improvements to Comment docs -- Editable, re-ordering conditionals, wording

Author: robinsowell

docs/comment/entries.md

@@ -22,7 +22,7 @@ Here is a basic example showing how you might use the comment tag:
       <p>By {name} on {comment_date format="%Y %m %d"}</p>
     {/exp:comment:entries}
 
-NOTE: **Important:** The Comment Entries tag should **not** be nested inside of a standard {exp:channel:entries} tag.
+NOTE: **Important:** The Comment Entries tag should **not** be nested inside of a standard {exp:channel:entries} tag. If you do, the outer tag will parse and resolve many of these variables and conditionals before the Comment Entries tag has the chance to do so.
 
 ## Parameters
 
@@ -158,12 +158,6 @@ This variable will always display the absolute total number of results that are
 
 The _opposite_ of `{absolute_count}`, in that it displays the entry count position counting backwards from the absolute total. Works across pagination, so the fifth entry in a list of fifteen entries would display "10".
 
-### `{allow_comments}`
-
-    {if allow_comments}
-
-TRUE / FALSE, Whether or not the entry being displayed allows comments. Typically used as a conditional.
-
 ### `{author}`
 
 The comment author's screen name, if a member; otherwise, this variable will display the name submitted with the comment.
@@ -196,10 +190,6 @@ The URL to the avatar image associated with the entry's author. Typically used a
 
     {if avatar} <img src="{avatar_url}" width="{avatar_image_width}" height="{avatar_image_height}" alt="{author}'s avatar" /> {/if}
 
-### `{if can_moderate_comment}`
-
-TRUE / FALSE, Whether a member has permission to edit a given comment AND/OR close that comment. Used in conjunction with [comment editing](comment/form.md#allowing-members-to-edit-comments-on-the-front-end).
-
 ### `{channel_id}`
 
 The ID number of the channel that the comment belongs to.
@@ -289,12 +279,6 @@ If five entries are being displayed per page, then for the fourth entry on the p
 
 The date on which the comment was edited. See [Date Variable Formatting](templates/date-variable-formatting.md) for more information.
 
-### `{editable}`
-
-    {if editable}Show Edit{/if}
-
-This variable will be used in a conditional to allow [comment editing](comment/form.md#allowing-members-to-edit-comments-on-the-front-end). It indicates whether a member has [permission to edit a given comment](control-panel/member-manager.md#createedit-all-member-roles).
-
 ### `{email}`
 
 The comment author's email address, if specified.
@@ -453,7 +437,15 @@ These are totally dynamic in that any profile field you create for your members
 
 [TOC=3]
 
-The following special conditionals are available:
+The following special conditionals are available.
+
+NOTE: **Important:** Avoid using Template Caching on any Template containing these conditional that are user-specific. If you do not avoid caching, then data will not be dynamic for each user. Instead, whoever happens to load the page when it gets cached will have their conditionals applied to every subsequent visitor until the cache expires.
+
+### `{if allow_comments}`
+
+    {if allow_comments} content {/if}
+
+TRUE / FALSE, Whether or not the entry being displayed allows comments. Typically used as a conditional.
 
 ### `{if avatar}`
 
@@ -463,20 +455,32 @@ This special conditional lets you conditionally display content if the current e
 
     {if avatar} <img src="{avatar_url}" width="{avatar_image_width}" height="{avatar_image_height}" alt="{author}'s avatar" /> {/if}
 
+### `{if can_moderate_comment}`
+
+TRUE / FALSE, Whether a member has permission to edit a given comment AND/OR close that comment. Used in conjunction with [comment editing](comment/form.md#allowing-members-to-edit-comments-on-the-front-end).
+
 ### `{if comments_expired}`
 
+    {if comments_expired} content {/if}
+
 If commenting has expired (and expiration is not set to be [overridden by moderation](comment/control-panel.md)), the contents of this conditional will be displayed.
 
 NOTE: **Note:** `{if no_results}` has precedence over this conditional. If there are no comments, this conditional is not evaluated.
 
 ### `{if comments_disabled}`
 
-    {if comments_disabled}
+    {if comments_disabled} content {/if}
 
 If commenting has been disabled, the contents of this conditional will be displayed.
 
 NOTE: **Note:** `{if no_results}` has precedence over this conditional. If there are no comments, this conditional is not evaluated.
 
+### `{if editable}`
+
+    {if editable} Show Edit Form {/if}
+
+TRUE / FALSE, This variable will be used in a conditional to allow [comment editing](comment/form.md#allowing-members-to-edit-comments-on-the-front-end). It indicates whether a member has [permission to edit a given comment](control-panel/member-manager.md#createedit-all-member-roles).
+
 ### `{if is_ignored}`
 
     {if is_ignored} content {/if}
@@ -509,7 +513,7 @@ Or you can use Javascript to allow the user to read the comment if they wish:
       <div id="{comment_id}" {if is_ignored}style="display: none;"{/if}>{comment}</div>
     {/exp:comment:entries}
 
-NOTE: **Important:** Avoid using Template Caching on any Template containing this conditional. If you do not avoid caching, then data will not be dynamic for each user. Instead, whoever happens to load the page when it is cached will have their ignore list applied to everyone until the cache expires.
+NOTE: **Important:** Avoid using Template Caching on any Template containing this conditional. If you cache this, whoever happens to load the page when it is first cached will have their ignore list applied to everyone until the cache is cleared.
 
 ### `{if no_results}`
 

docs/comment/form.md

@@ -74,7 +74,7 @@ This is a **required** parameter if you are using comment previews indicating wh
 
 You can hard code the comment for tag to display a comment form for a specific channel entry by its URL title.
 
-NOTE: **Note:** This parameter takes precedence over any entry specified dynamically in the URL, so when using this parameter you will want to make sure it is clear to the user which entry the displayed comment form belong to.
+NOTE: **Note:** This parameter takes precedence over any entry specified dynamically in the URL, so when using this parameter you will want to make sure it is clear to the user which entry the displayed comment form belongs to.
 
 #### `channel=`
 
@@ -174,7 +174,7 @@ The following conditionals are available:
 
 ## Allowing Members to Edit Comments on the Front End
 
-The available tags and variables allow you to write your own client side code for implementing comment editing. The following is a simplified example using jQuery.
+The available tags and variables allow you to write your own client-side code for implementing comment editing. The following is a simplified example using jQuery.
 
 ### Example Code
 
@@ -227,13 +227,13 @@ A request for an edit will return a response array. In the case of an error, an
 
 ### Editing Permissions
 
-The {if editable} conditional in the Comment Entries tag outputs content when the viewing member has permission to edit the comment indicated while the {if can_moderate_comment} outputs content if they have permission to close the comment.
+By using the [{if editable}](/comment/entries.html#if-editable) conditional in the Comment Entries tag, you can output a link, instructions or a form if the viewing member has permission to edit the comment, and by using the {if can_moderate_comment} you can display whatever is appropriate if the viewing member has permission to moderate (close) the comment.
 
-For regular members, in order to edit comments they must be a logged in member, the author of the comment, and the editing time limit must not have expired.
+For default regular members, in order to edit a comment, they must be logged in, the author of the comment, and the editing time limit must not have expired. If a member has a role with permission to edit the comments of any entry, that member will have edit permissions regardless of the editing time limit.
 
-Comment moderators may close the comment. Superadmins will always have {editable} and {can_moderate_comment} permissions on any comment.
+Comment moderators may close the comment. The edit time limit does not apply to moderators. 
 
-Lastly, if a member is in a group with permission to edit comments in any entry, they will have edit permissions. The edit time limit does not apply to moderators.
+Superadmins will always have {editable} and {can_moderate_comment} permissions on any comment.
 
 ### Customizing Client-Side Code