doc: improve text about comments
to catch problems like
@@ -73,54 +73,73 @@ note= this will rarely used within specifications, but is directly
[comment]
type= string
status= deprecated
-usedby/plugin= (keytometa)
+usedby/plugin= keytometa
description= the users comment about the key (mostly its value)
- the first line is the comment after a key-value
+ the first line is the comment after a key-value (in the same line)
further lines are the lines before a key-value
+
+ This metadata is deprecated because it assumes line-based comments
+ and cannot preserve formatting within comments.
note= if used within specifications it refers to the specification, not
the key. Use `description` to refer to the key.
-
[comment/#]
status= implemented
usedby/plugin= hosts
type= string
-description= comment line preceding an actual key
- Except #0, which is the inline key (in the same line).
- The comment numbering starts from top to bottom. The comment
- directly above the key is the last entry in the array and
- the topmost comment belonging to the key is #1.
+description= A comment preceding or in-line with a key.
+
+ - #0 is the inline comment (in the same line).
+ - The comment numbering starts from top (#1) to bottom (#n).
+ - The comment directly above the key is the last entry in the array (#n).
+ - The topmost comment belonging to the key is (#1).
+
Comment keys that are not above any key (comments in the last
lines of files) are added to the parentkey.
- It allows:
+ The array of comments allows:
+
+ - to structure comments, which are not line-based
- to restore formatting, including:
- inline comments
- spaces before comments
- empty lines
- - to distinguish between different kinds of comments and empty lines
- - to tag every single comment line, which increases extensibility
+ - to distinguish between different kinds of comments
+ - to tag every comment, which increases extensibility
- It needs, however, an API so that the user is not required to fiddle
- with all these details. (to be done)
-note= Other libraries doing similar things:
- http://commons.apache.org/proper/commons-configuration/apidocs/org/apache/commons/configuration2/PropertiesConfigurationLayout.html
- http://code.google.com/p/bracket-properties/
+ The plugin need to take care that only valid characters are
+ present in the comment.
+ E.g. on line-based comments, no newlines must be present.
+note= if used within specifications it refers to the specification, not
+ the key. Use `description` to refer to the key.
[comment/#/start]
status= implemented
usedby/plugin= hosts
type= string
-description= determines the character used to start this line of comment
- None if its an empty line
+description= Determines the character(s) used to start this comment.
+
+ This meta-key is empty if its an empty line/comment.
+
+ The default on absence of this key is plugin-specific.
+ Some comment start character should be assumed then.
+
+ The plugin needs to make sure that every comment is actually
+ commented out. An error needs to be emitted if there is no
+ start symbol that will be recognized as comment.
+example= ;
[comment/#/space]
status= implemented
usedby/plugin= hosts
type= string
-description= the spaces/tabs used between a comment and the beginning of the
- line or after end of payload data (for inline comments)
- If no start-comment token was found, only space and no comment is present.
+description= The spaces/tabs used between a comment and the beginning of the
+ line or after end of payload data (for inline comments).
+
+ If no start key is present, only space and no comment is present.
+
+ The plugin needs to make sure that all spaces present are allowed.
+ An error needs to be emitted if non-ignored spaces are present.
example=
