Merge pull request #1 from docs/hubwriter-patch-1

Update code-description.md

code-description.md

@@ -463,7 +463,8 @@ We do the following for every tag we encounter during parsing.
 
   Note: that `currentTagEnd` is actually the character after the closing bracket.
 
-- Check whether the cursor position is before the beginning of the tag. If it is we set `cursorIsAfterTag` to false.
+- Check whether the cursor position is after the start of the current tag (in which case the tag may affect the text at the cursor position). If it's not we set `cursorIsAfterTagStart` to `false`.
+- Check whether the cursor position is after the end of the current tag. If it's not we set `cursorIsAfterTagEnd` to `false`. We only use this for `endif` tags.
 - Create a new element in the `versionTags` array, containing these properties:
   - **tagID**: The unique ID (`tagCounter` number).
   - **tagSet**: The tag set ID (`tagSetID[nestingLevel]` number).
@@ -473,43 +474,43 @@ We do the following for every tag we encounter during parsing.
 #### `ifversion`
 
 When we find an `ifversion` tag we:
-- Increment `nestingLevel`. Initially this is -1, so this becomes 0 for an un-nested tag set and 1 for the first nesting level. This variable needs to survive from one tag processing to the next
+- Increment `nestingLevel`. Initially this is -1, so this becomes 0 for an un-nested tag set and 1 for the first nesting level. This variable needs to survive from one tag processing to the next.
 - Assign `tagCounter` to `tagSetID[nestingLevel]`. This is the ID of the tag set that this tag belongs to (always the same as the ifversion ID). This array needs to survive from one tag processing to the next.
-- If `cursorIsAfterTag` is true we:
+- If `cursorIsAfterTagStart` is true we:
   - Assign `tagCounter` to `currentTagSpan[nestingLevel]`. This array needs to survive from one tag processing to the next so that we can determine which tag span the cursor is currently within, and therefore which tags we need to highlight.
-  - Get the version from the tag (e.g. "ghes"), using `match[1]` from the regular expression.
-  - Assign the version to `versionDescription[nestingLevel]`.
-  - Set `elsedVersions[nestingLevel]` to `"NOT " + versionDescription[nestingLevel]` (e.g. "NOT ghes"). For nested `ifversion` tags we prepend "\nAND " to the start of the string. This variable needs to survive from one tag processing to the next, so that we can build up a string that describes the versioning for the `else` tag in the tag set.
+  - Get the version from the tag (e.g. "ghes"), using `match[2]` from the regular expression.
+  - Assign the `match[2]` to `versionDescription[nestingLevel]` for an un-nested tag set. For nested tag sets assign `"AND " + match[2]` (e.g. "AND ghes").
+  - Assign `"NOT " + match[2]` to `versionDescription[nestingLevel]` for an un-nested tag set. For nested tag sets assign `"AND NOT " + match[2]` (e.g. "AND NOT ghes"). This variable needs to survive from one tag processing to the next, so that we can build up a string that describes the versioning for the `else` tag in the tag set.
 
 #### `elsif`
 
 When we find an `elsif` tag:
-- If `cursorIsAfterTag` is true we:
-  - Assign `tagSetID[nestingLevel]` to `currentTagSpan[nestingLevel]`.
-  - Get the version from the tag (e.g. "ghec").
-  - Assign the version to `versionDescription[nestingLevel]`.
-  - Set `elsedVersions[nestingLevel]` to `elsedVersions[nestingLevel] + " \nAND NOT " + versionDescription[nestingLevel]` (e.g. "NOT ghes \nAND NOT ghec").
+- If `cursorIsAfterTagStart` is true we:
+  - Assign `tagCounter` to `currentTagSpan[nestingLevel]`. 
+  - Assign the version to `versionDescription[nestingLevel]`, prepending "AND " if we're in a nested tag set.
+  - Set `elsedVersions[nestingLevel]` to `elsedVersions[nestingLevel] + " \nAND NOT " + match[2]` (e.g. "NOT ghes \nAND NOT ghec").
+
 Note that we don't assign a value to `tagSetID[nestingLevel]` because this tag doesn't start a new tag set. It belongs to the same tag set as the `ifversion` tag. So we use the same `tagSetID[nestingLevel]` value that we set for the `ifversion` tag.
 
 #### `else`
 
 When we find an `else` tag:
-- If `cursorIsAfterTag` is true we:
-  - Assign `tagSetID[nestingLevel]` to `currentTagSpan[nestingLevel]`.
-  - If `nestingLevel` is >0, we set `versionDescription[nestingLevel]` to " AND ".
-  - Set `versionDescription[nestingLevel]` to `versionDescription[nestingLevel] + elsedVersions[nestingLevel]`.
-As with `elsif` we again reuse the unmodified `tagSetID[nestingLevel]` value that we set for the `ifversion` tag.
+- If `cursorIsAfterTagStart` is true we:
+  - Assign `tagCounter` to `currentTagSpan[nestingLevel]`. 
+  - Assign the `elsedVersions[nestingLevel]` to `versionDescription[nestingLevel]`, prepending "AND " if we're in a nested tag set.
 
 #### `endif`
 
 When we find an `endif` tag:
-- If `cursorIsAfterTag` is true we:
+- If `cursorIsAfterTagEnd` is true we:
   - Delete the last element in the `currentTagSpan`, `versionDescription` and `elsedVersions` arrays.
-  - Decrement `nestingLevel`. At each `endif` we're stepping out of a level of nesting, or out of versioning altogether this is the `endif` for an un-nested tag set (in which case `nestingLevel` returns to -1).
+
 As with `elsif` we again reuse the unmodified `tagSetID[nestingLevel]` value that we set for the `ifversion` tag.
 
 Note: the cursor can never be within an `endif` tag span, because `endif` tags have no tag span. So we'll never use the `tagID` or `versionDescription` properties of an `endif` tag. We'll only use the `tagSet` property (to identify the `endif` tag to highlight when the cursor is somewhere else within this tag set) and the `positionVersionTagStart` and `positionVersionTagEnd` properties (to tell VS Code which characters to highlight for this tag).
 
+After we create the `versionTags` entry for this `endif` tag, we decrement `nestingLevel`. We do this because, after each `endif` tag, we step out of a level of nesting, or out of versioning altogether this is the `endif` for an un-nested tag set (in which case `nestingLevel` returns to -1).
+
 ### Regular expression
 
 We use the following regular expression to find version tags in the Markdown file: