fix issues in the tests and code + add documentation

docs/user-docs/annotation.md

@@ -91,7 +91,7 @@ element and its nested model elements.
 Supported JSON payload patterns:
 
 - `{`... `"comment":` _comment_ || `{` _context_: _ccomment_ `}` ...`}`: The _comment_ (tooltip) to be used in place of the model element's original comment. Set this to `false` if you don't want any tooltips.
-- `{`... `"comment_display":` `{` _context_: `{` `"table_comment_display"`: _comment_display_ `,` `"column_comment_display"`: _comment_display_ `}` ... `}`
+- `{`... `"comment_display":` `{` _context_: `{` `"table_comment_display"`: _comment_display_ `,` `"column_comment_display"`: _comment_display_ `,` `"comment_render_markdown"`: _comment_render_markdown_ `}` ... `}`
 - `{`... `"name":` _name_ ...`}`: The _name_ to use in place of the model element's original name.
 - `{`... `"markdown_name"`: _markdown_ `}`: The _markdown_ to use in place of the model element's original name.
 - `{`... `"name_style":` `{` `"underline_space"`: _uspace_ `,` `"title_case":` _tcase_ `,` `"markdown"`: _render_ `}` ...`}`: Element name conversion instructions.
@@ -111,6 +111,11 @@ Supported JSON _comment_display_ patterns:
 - `tooltip`: Set to tooltip to show the comment as a hover over tooltip.
 - `inline`: Set to inline to show the comment as an inline tooltip.
 
+Supported JSON _comment_render_markdown_ patterns:
+
+- `false`: Don't treat the defined `comment` on this model and its descendants as markdown.
+- `true`: Treat the defined `comment` on this model and its descendants as markdown.
+
 Supported JSON _uspace_ patterns:
 
 - `true`: Convert underline characters (`_`) into space characters in model element names.
@@ -158,7 +163,7 @@ Supported JSON _context_ patterns:
 #### Tag: 2015 Display Settings Hierarchy
 
 - The `"comment"` setting applies *only* to the model element which is annotated.
-  - Currently the contextualized `comment` is only supported for tables.
+- The `"_comment_render_markdown_": false` should be used if you don't want us to treat the comment as a markdown value. By default we're assuming given comments are markdown.
 - The `"table_comment_display"` and `"column_comment_display"` setting applies *only* to the model element which is annotated.
   - Currently the contextualized `table_comment_display` is supported for `compact` context for the title and the tables in detailed context when they are part of a foreign key relationship in `visible-columns` or `visible-foreign-keys`.
   - `column_comment_display` is accepted as a parameter, but currently doesn't do anything.
@@ -426,6 +431,7 @@ Supported JSON payload patterns:
 - `{` ... `"from_name":` _fname_ ... `}`: The _fname_ string is a preferred name for the set of entities containing foreign key references described by this constraint.
 - `{` ... `"to_name":` _tname_ ... `}`: The _tname_ string is a preferred name for the set of entities containing keys described by this constraint.
 - `{` ... `"from_comment":` _comment_ ... `}`: The _comment_ string is a preferred comment for the set of entities containing keys described by this constraint.
+- `{` ... `"comment_render_markdown":` _boolean_value_ ... `}`: The _boolean_value_ dictates whether the comments for this foreignkey should be treated as markdown or not. If not defined, its value will be inherited from the table (which could be inherited from the schema or the catalog. If it's not defined on any of the models, the default behavior is to treat comments as markdown).
 - `{` ... `"to_comment":` _comment_ ... `}`: The _comment_ string is a preferred comment for the set of entities containing keys described by this constraint.
 - `{` ... `"from_comment_display":` _comment_display_ ... `}`: The display mode for the tooltip. Set to `inline` to show it as text or `tooltip` to show as a hover tooltip.
     - Currently the `comment_display` is only supported for foreign key relationships in detailed context when they are part of `visible-columns` or `visible-foreign-keys`.
@@ -1300,6 +1306,7 @@ The following attributes can be used to manipulate the presentation settings of
 
 - `markdown_name`: The markdown to use in place of the default heuristics for title of column.
 - `comment`: The tooltip to be used in place of the default heuristics for the column. Set this to `false` if you don't want any tooltip.
+- `comment_render_markdown`: A boolean value that dictates whether the comment should be treated as markdown or not. If not defined, its value will be inherited from the underlying column or table (which could be inherited from the schema or the catalog. If it's not defined on any of the models, the default behavior is to treat comments as markdown).
 - `comment_display`: The display mode for the tooltip. Set to `inline` to show it as text or `tooltip` to show as a hover tooltip.
   - Currently `comment_display` is only supported for related tables in detailed context.
 - `hide_column_header`: Hide the column header (and still show the value). This is only supported in `detailed` context of `visible-columns` annotation.

docs/user-docs/column-directive.md

@@ -23,6 +23,7 @@ Column directive allows instruction of a data source and modification of its pre
   - [2. Presentation properties](#2-presentation-properties)
     - [markdown\_name](#markdown_name)
     - [comment](#comment)
+    - [comment\_render\_markdown](#comment-render-markdown)
     - [comment\_display](#comment_display)
     - [hide\_column\_header](#hide_column_header)
     - [self-link](#self-link)
@@ -359,6 +360,14 @@ In Chaise, comment is displayed as tooltip associated with columns. To change th
 
     "comment": "New comment"
 
+#### comment_render_markdown
+
+A boolean value that dictates whether the comment should be treated as markdown or not. If not defined, its value will be inherited from the underlying column or table which could be inherited from the schema or the catalog. If it's not defined on any of the models, the default behavior is to treat comments as markdown.
+
+    "comment_render_markdown": false
+
+This boolean works independent of the `comment` property. Which means that you can define `commen_render_markdown` to be used in combination with the comment that is derived based on the heuristics.
+
 #### comment_display
 
 By default Chaise will display `comment` as a tooltip. Set this value to `inline` to show it as text or `tooltip` to show as a hover tooltip. This property is only supported for related tables in detailed context of `visible-foreign-keys` annotation, and is not honored in other annotations.
@@ -404,7 +413,7 @@ While generating a default presentation for all outbound foreign key paths, ERMr
 
 ##### selector_ux_mode
 
-While generating a default presentation in `entry` mode for single outbound foreign key paths, Chaise will show a modal popup dialog for selecting rows. Using this attribute, you can modify this behavior. If this attribute is missing, we are going to use the inherited behavior from the [foreign key](annotation.md#tag-2016-foreign-key) annotation defined on the foreign key relationship. If that one is missing too, [table display](annotation.md#tag-2016-table-display) annotation will be applied. Supported values are `"facet-search-popup"` and `"simple-search-dropdown"`, with `"facet-search-popup"` being the default. 
+While generating a default presentation in `entry` mode for single outbound foreign key paths, Chaise will show a modal popup dialog for selecting rows. Using this attribute, you can modify this behavior. If this attribute is missing, we are going to use the inherited behavior from the [foreign key](annotation.md#tag-2016-foreign-key) annotation defined on the foreign key relationship. If that one is missing too, [table display](annotation.md#tag-2016-table-display) annotation will be applied. Supported values are `"facet-search-popup"` and `"simple-search-dropdown"`, with `"facet-search-popup"` being the default.
 
 ##### show_key_link
 

js/column.js

@@ -294,15 +294,20 @@ ReferenceColumn.prototype = {
             var comment = null, commentDisplayMode, commentRenderMarkdown;
             if (this._simple) {
                 var display = this._baseCols[0].getDisplay(this._context);
-                comment = display.comment ? display.comment.unformatted : null;
+                comment = display.comment;
                 commentDisplayMode = display.commentDisplayMode;
                 commentRenderMarkdown = display.commentRenderMarkdown;
             }
 
             if (!this.sourceObject) {
                 this._comment = comment;
             } else {
-                this._comment = _processSourceObjectComment(this.sourceObject, comment, commentRenderMarkdown, commentDisplayMode);
+                this._comment = _processSourceObjectComment(
+                    this.sourceObject,
+                    comment ? comment.unformatted : null,
+                    commentRenderMarkdown,
+                    commentDisplayMode
+                );
             }
 
         }
@@ -1351,42 +1356,43 @@ PseudoColumn.prototype._determineInputDisabled = function () {
 Object.defineProperty(PseudoColumn.prototype, "comment", {
     get: function () {
         if (this._comment === undefined) {
-            var getDefaultCommentProps = function (self) {
+            var getComment = function (self) {
                 if (self.hasAggregate) {
+                    // if defined on the sourceObject use it.
+                    var com = _processSourceObjectComment(self.sourceObject);
+                    if (com) {
+                        return com;
+                    }
+
+                    // otherwise generate one
                     var agIndex = module._pseudoColAggregateFns.indexOf(self.sourceObject.aggregate);
                     var dname = self._baseCols[0].displayname.unformatted;
                     if (self.isEntityMode) {
                         dname = self._baseCols[0].table.displayname.unformatted;
                     }
 
-                    return {
-                        comment: [module._pseudoColAggregateExplicitName[agIndex], dname].join(" "),
-                        commentDisplayMode: module._commentDisplayModes.tooltip,
-                        commentRenderMarkdown: false
-                    };
+                    return _processModelComment([module._pseudoColAggregateExplicitName[agIndex], dname].join(" "), false);
                 }
 
-                var temp;
+                // if it's not aggregate, we can get it from the table or column depending on entity mode:
+                var disp, commentDisplayMode;
                 if (!self.isEntityMode) {
-                    temp = self._baseCols[0].getDisplay(self._context);
-                    return {
-                        comment: temp.comment ? temp.comment.unformatted: null,
-                        commentDisplayMode: temp.commentDisplayMode,
-                        commentRenderMarkdown: temp.commentRenderMarkdown
-                    };
+                    disp = self._baseCols[0].getDisplay(self._context);
+                    commentDisplayMode = disp.commentDisplayMode;
+                } else {
+                    disp = self.table.getDisplay(self._context);
+                    commentDisplayMode = disp.tableCommentDisplayMode;
                 }
 
-                // self.table should be leaf table
-                temp = self.table.getDisplay(self._context);
-                return {
-                    comment: temp.comment ? temp.comment.unformatted: null,
-                    commentDisplayMode: temp.tableCommentDisplayMode,
-                    commentRenderMarkdown: temp.commentRenderMarkdown
-                };
-            };
+                return _processSourceObjectComment(
+                    self.sourceObject,
+                    disp.comment ? disp.comment.unformatted : null,
+                    disp.commentRenderMarkdown,
+                    commentDisplayMode
+                );
+            }
 
-            var def = getDefaultCommentProps(this);
-            this._comment = _processSourceObjectComment(this.sourceObject, def.comment, def.commentRenderMarkdown, def.commentDisplayMode);
+            this._comment = getComment(this);
         }
         return this._comment;
     }

js/reference.js

@@ -4087,7 +4087,7 @@
 
                 // comment
                 if (fkDisplay.fromComment) {
-                    comment = fkDisplay.fromComment;
+                    comment = fkDisplay.fromComment.unformatted;
                 } else {
                     comment = tableDisplay.comment ? tableDisplay.comment.unformatted : null;
                 }

js/utils/helpers.js

@@ -848,11 +848,10 @@
     };
 
     /**
-     * Given an input string for the comment, will return the actual strng that should be used.
-     *   - if =false : returns empty string.
-     *   - if =string: returns the string.
-     *   - otherwise returns null
-     * TODO update comment
+     * Turn a comment annotaiton/string value into a proper comment object.
+     * @param {string|null|false} comment
+     * @param {boolean=true} isMarkdown whether the given comment should be rendered as markdown (default: true).
+     * @param {string} displayMode the display mode of the comment (inline, tooltip)
      * @private
      */
     _processModelComment = function (comment, isMarkdown, displayMode) {