From b602f7240b9ad06eb9e8ea029efa32701a97ebd9 Mon Sep 17 00:00:00 2001 From: Martin Staffa Date: Thu, 5 Oct 2017 17:10:11 +0200 Subject: [PATCH 1/3] chore(doc-gen): show void attributes in directive usage When a directive doesn't take a value, its name is not included in the parameters, which previously meant that the directive name was missing from the Attribute / CSS Class usage section of the docs. This commit adds the name to the Usage section when it is missing from the parameters. Closes #14045 --- .../templates/ngdoc/api/directive.template.html | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/config/templates/ngdoc/api/directive.template.html b/docs/config/templates/ngdoc/api/directive.template.html index fd9c9972f1c1..0a3480eee988 100644 --- a/docs/config/templates/ngdoc/api/directive.template.html +++ b/docs/config/templates/ngdoc/api/directive.template.html @@ -29,10 +29,23 @@

Usage

{% endif -%} + + {% set hasNameAsParam = false %} + + {# when a directive's name is not a parameter (i.e. doesn't take a value), + add the directive name to the list of attributes and/or css classes #} + + {%- for param in doc.params %} + {% set hasNameAsParam = true if param.name === doc.name else hasNameAsParam %} + {%- endfor %} + {%- if doc.restrict.attribute -%}
  • as attribute: {% code %} <{$ doc.element $} + {%- if not hasNameAsParam %} + {$ lib.directiveParam(doc.name, {}, '', '') $} + {%- endif -%} {%- for param in doc.params %} {$ lib.directiveParam(param.name, param.type, '="', '"') $} {%- endfor %}> @@ -43,10 +56,14 @@

    Usage

    {% endif -%} {%- if doc.restrict.cssClass -%} +
  • as CSS class: {% code %} {% set sep = joiner(' ') %} <{$ doc.element $} class=" + {%- if not hasNameAsParam -%} + {$ sep() $}{$ lib.directiveParam(doc.name, {}, '', '') $} + {%- endif -%} {%- for param in doc.params -%} {$ sep() $}{$ lib.directiveParam(param.name, param.type, ': ', ';') $} {%- endfor %}"> ... From 314c8b905b4f6cd0cfb7cba53d19da9e86138b7e Mon Sep 17 00:00:00 2001 From: Martin Staffa Date: Fri, 13 Oct 2017 14:55:48 +0200 Subject: [PATCH 2/3] test(docs-app): ensure correct attribute usage --- docs/app/e2e/usage.scenario.js | 55 ++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/app/e2e/usage.scenario.js diff --git a/docs/app/e2e/usage.scenario.js b/docs/app/e2e/usage.scenario.js new file mode 100644 index 000000000000..7f438430352b --- /dev/null +++ b/docs/app/e2e/usage.scenario.js @@ -0,0 +1,55 @@ +'use strict'; + +/** + * This scenario checks if the usage section for selected directives is rendered correctly + */ + +describe('usage section', function() { + + describe('should list the directive name', function() { + + it('when directive name is a parameter with a value', function() { + browser.get('build/docs/index.html#!/api/ng/directive/ngInclude'); + + // Ensure that ngInclude appears as an argument + var args = element(by.className('input-arguments')); + + var paramNames = args.all(by.css('tr td:nth-child(1)')); + + expect(paramNames.getText()).toContain('ngInclude | src'); + + var usage = element(by.className('usage')); + + var asElement = usage.element(by.cssContainingText('li', 'as element')); + var asAttribute = usage.element(by.cssContainingText('li', 'as attribute')); + var asCssClass = usage.element(by.cssContainingText('li', 'as CSS class')); + + expect(asElement.element(by.cssContainingText('span.tag', 'ng-include')).isPresent()).toBe(true); + expect(asAttribute.element(by.cssContainingText('span.atn', 'ng-include')).isPresent()).toBe(true); + expect(asCssClass.element(by.cssContainingText('span.atv', 'ng-include')).isPresent()).toBe(true); + }); + + + it('when directive name is a void parameter', function() { + browser.get('build/docs/index.html#!/api/ngRoute/directive/ngView'); + + // Ensure that ngView does not appear as an argument + var args = element(by.className('input-arguments')); + + var paramNames = args.all(by.css('tr td:nth-child(1)')); + + expect(paramNames.getText()).not.toContain('ngView'); + + var usage = element(by.className('usage')); + + var asElement = usage.element(by.cssContainingText('li', 'as element')); + var asAttribute = usage.element(by.cssContainingText('li', 'as attribute')); + var asCssClass = usage.element(by.cssContainingText('li', 'as CSS class')); + + expect(asElement.element(by.cssContainingText('span.tag', 'ng-view')).isPresent()).toBe(true); + expect(asAttribute.element(by.cssContainingText('span.atn', 'ng-view')).isPresent()).toBe(true); + expect(asCssClass.element(by.cssContainingText('span.atv', 'ng-view')).isPresent()).toBe(true); + }); + + }); +}); From 8e32f98edd2f81e2c01b5c4024d73ecb07f8e5bb Mon Sep 17 00:00:00 2001 From: Martin Staffa Date: Tue, 17 Oct 2017 13:42:25 +0200 Subject: [PATCH 3/3] refactor the tests --- .../e2e/api-docs/directive-pages.scenario.js | 58 +++++++++++++++++++ docs/app/e2e/usage.scenario.js | 55 ------------------ 2 files changed, 58 insertions(+), 55 deletions(-) create mode 100644 docs/app/e2e/api-docs/directive-pages.scenario.js delete mode 100644 docs/app/e2e/usage.scenario.js diff --git a/docs/app/e2e/api-docs/directive-pages.scenario.js b/docs/app/e2e/api-docs/directive-pages.scenario.js new file mode 100644 index 000000000000..cec2d484545d --- /dev/null +++ b/docs/app/e2e/api-docs/directive-pages.scenario.js @@ -0,0 +1,58 @@ +'use strict'; + +describe('directives', function() { + + describe('parameter section', function() { + + it('should show the directive name only if it is a param (attribute) with a value', function() { + browser.get('build/docs/index.html#!/api/ng/directive/ngInclude'); + expect(getParamNames().getText()).toContain('ngInclude | src'); + + browser.get('build/docs/index.html#!/api/ngRoute/directive/ngView'); + expect(getParamNames().getText()).not.toContain('ngView'); + }); + }); + + describe('usage section', function() { + + it('should show the directive name if it is a param (attribute) with a value', function() { + browser.get('build/docs/index.html#!/api/ng/directive/ngInclude'); + + expect(getUsageAs('element', 'ng-include').isPresent()).toBe(true); + expect(getUsageAs('attribute', 'ng-include').isPresent()).toBe(true); + expect(getUsageAs('CSS class', 'ng-include').isPresent()).toBe(true); + }); + + it('should show the directive name if it is a void param (attribute)', function() { + browser.get('build/docs/index.html#!/api/ngRoute/directive/ngView'); + + expect(getUsageAs('element', 'ng-view').isPresent()).toBe(true); + expect(getUsageAs('attribute', 'ng-view').isPresent()).toBe(true); + expect(getUsageAs('CSS class', 'ng-view').isPresent()).toBe(true); + }); + }); +}); + +function getParamNames() { + var argsSection = element(by.className('input-arguments')); + + var paramNames = argsSection.all(by.css('tr td:nth-child(1)')); + + return paramNames; +} + +// Based on the type of directive usage, the directive name will show up in the code block +// with a specific class +var typeClassMap = { + element: 'tag', + attribute: 'atn', + 'CSS class': 'atv' +}; + +function getUsageAs(type, directiveName) { + var usage = element(by.className('usage')); + + var as = usage.element(by.cssContainingText('li', 'as ' + type)); + + return as.element(by.cssContainingText('span.' + typeClassMap[type], directiveName)); +} diff --git a/docs/app/e2e/usage.scenario.js b/docs/app/e2e/usage.scenario.js deleted file mode 100644 index 7f438430352b..000000000000 --- a/docs/app/e2e/usage.scenario.js +++ /dev/null @@ -1,55 +0,0 @@ -'use strict'; - -/** - * This scenario checks if the usage section for selected directives is rendered correctly - */ - -describe('usage section', function() { - - describe('should list the directive name', function() { - - it('when directive name is a parameter with a value', function() { - browser.get('build/docs/index.html#!/api/ng/directive/ngInclude'); - - // Ensure that ngInclude appears as an argument - var args = element(by.className('input-arguments')); - - var paramNames = args.all(by.css('tr td:nth-child(1)')); - - expect(paramNames.getText()).toContain('ngInclude | src'); - - var usage = element(by.className('usage')); - - var asElement = usage.element(by.cssContainingText('li', 'as element')); - var asAttribute = usage.element(by.cssContainingText('li', 'as attribute')); - var asCssClass = usage.element(by.cssContainingText('li', 'as CSS class')); - - expect(asElement.element(by.cssContainingText('span.tag', 'ng-include')).isPresent()).toBe(true); - expect(asAttribute.element(by.cssContainingText('span.atn', 'ng-include')).isPresent()).toBe(true); - expect(asCssClass.element(by.cssContainingText('span.atv', 'ng-include')).isPresent()).toBe(true); - }); - - - it('when directive name is a void parameter', function() { - browser.get('build/docs/index.html#!/api/ngRoute/directive/ngView'); - - // Ensure that ngView does not appear as an argument - var args = element(by.className('input-arguments')); - - var paramNames = args.all(by.css('tr td:nth-child(1)')); - - expect(paramNames.getText()).not.toContain('ngView'); - - var usage = element(by.className('usage')); - - var asElement = usage.element(by.cssContainingText('li', 'as element')); - var asAttribute = usage.element(by.cssContainingText('li', 'as attribute')); - var asCssClass = usage.element(by.cssContainingText('li', 'as CSS class')); - - expect(asElement.element(by.cssContainingText('span.tag', 'ng-view')).isPresent()).toBe(true); - expect(asAttribute.element(by.cssContainingText('span.atn', 'ng-view')).isPresent()).toBe(true); - expect(asCssClass.element(by.cssContainingText('span.atv', 'ng-view')).isPresent()).toBe(true); - }); - - }); -});