Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit 5fc3168

Browse files
petebacondarwinpetebacondarwin
committed
chore(docs): deprecation notices for methods and properties
Closes #15351
1 parent 919eb2d commit 5fc3168

14 files changed

+210
-100
lines changed

‎docs/app/assets/css/docs.css

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -662,6 +662,11 @@ ul.events > li {
662662
max-width: 100%;
663663
}
664664

665+
.deprecation .title {
666+
float: left;
667+
margin-right: 5px;
668+
}
669+
665670
@media only screen and (min-width: 769px) {
666671
[ng-include="partialPath"].ng-hide {
667672
display: block !important;

‎docs/config/index.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,12 @@ module.exports = new Package('angularjs', [
5252

5353

5454
.config(function(parseTagsProcessor) {
55+
parseTagsProcessor.tagDefinitions.push(require('./tag-defs/deprecated')); // this will override the jsdoc version
5556
parseTagsProcessor.tagDefinitions.push(require('./tag-defs/tutorial-step'));
5657
parseTagsProcessor.tagDefinitions.push(require('./tag-defs/sortOrder'));
5758
parseTagsProcessor.tagDefinitions.push(require('./tag-defs/installation'));
5859
parseTagsProcessor.tagDefinitions.push(require('./tag-defs/this'));
60+
5961
})
6062

6163

‎docs/config/tag-defs/deprecated.js

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
'use strict';
2+
3+
var OPTION_MATCHER = /^\s*([\w-]+)="([^"]+)"\s+([\s\S]*)/;
4+
var VALID_OPTIONS = ['sinceVersion', 'removeVersion'];
5+
6+
module.exports = {
7+
name: 'deprecated',
8+
transforms: function(doc, tag, value) {
9+
var result = {};
10+
var invalidOptions = [];
11+
value = value.trim();
12+
while(OPTION_MATCHER.test(value)) {
13+
value = value.replace(OPTION_MATCHER, function(_, key, value, rest) {
14+
if (VALID_OPTIONS.indexOf(key) !== -1) {
15+
result[key] = value;
16+
} else {
17+
invalidOptions.push(key);
18+
}
19+
return rest;
20+
});
21+
}
22+
if (invalidOptions.length > 0) {
23+
throw new Error('Invalid options: ' + humanList(invalidOptions) + '. Value options are: ' + humanList(VALID_OPTIONS));
24+
}
25+
result.description = value;
26+
return result;
27+
}
28+
};
29+
30+
function humanList(values, sep, lastSep) {
31+
if (sep === undefined) sep = ', ';
32+
if (lastSep === undefined) lastSep = ' and ';
33+
34+
return values.reduce(function(output, value, index, list) {
35+
output += '"' + value + '"';
36+
switch(list.length - index) {
37+
case 1: return output;
38+
case 2: return output + lastSep;
39+
default: return output + sep;
40+
}
41+
}, '');
42+
}

‎docs/config/tag-defs/deprecated.spec.js

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
var tagDef = require('./deprecated');
2+
3+
describe('deprecated tag', function() {
4+
describe('transforms', function() {
5+
it('should return the trimmed value if no options', function() {
6+
var tag = tagDef.transforms({}, {}, 'This is the description');
7+
expect(tag.description).toEqual('This is the description');
8+
});
9+
10+
it('should read options', function() {
11+
var tag = tagDef.transforms({}, {}, ' sinceVersion="v1.3.4" removeVersion="v1.4.5" what is left is description');
12+
expect(tag.description).toEqual('what is left is description');
13+
expect(tag.sinceVersion).toEqual('v1.3.4');
14+
expect(tag.removeVersion).toEqual('v1.4.5');
15+
});
16+
17+
it('should cope with carriage returns', function() {
18+
var tag = tagDef.transforms({}, {}, '\nsinceVersion="v1.3.4"\nremoveVersion="v1.4.5"\nwhat is left is description');
19+
expect(tag.description).toEqual('what is left is description');
20+
expect(tag.sinceVersion).toEqual('v1.3.4');
21+
expect(tag.removeVersion).toEqual('v1.4.5');
22+
})
23+
24+
it('should error if there is an invalid option', function() {
25+
expect(function() {
26+
tagDef.transforms({}, {}, ' fromVersion="v1.3.4" toVersion="v1.4.5" what is left is description');
27+
}).toThrowError('Invalid options: "fromVersion" and "toVersion". Value options are: "sinceVersion" and "removeVersion"');
28+
});
29+
});
30+
});

‎docs/config/templates/app/runnableExample.template.html

Lines changed: 0 additions & 26 deletions
This file was deleted.

‎docs/config/templates/examples/runnableExample.template.html

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,26 @@
1-
{# Be aware that we need these extra new lines here or marked will not realise that the <div>
1+
{# Be aware that we need these extra new lines here or marked will not realize that the <div>
22
is HTML and wrap each line in a <p> - thus breaking the HTML #}
33

4+
<div>
5+
<plnkr-opener example-path="{$ doc.path $}"></plnkr-opener>
46

5-
<div class="runnable-example"
6-
path="{$ doc.example.deployments.default.path $}"
7-
{%- for attrName, attrValue in doc.example.attributes %}
8-
{$ attrName $}="{$ attrValue $}"{% endfor %}>
7+
<div class="runnable-example"
8+
path="{$ doc.example.deployments.default.path $}"
9+
{%- for attrName, attrValue in doc.example.attributes %}
10+
{$ attrName $}="{$ attrValue $}"{% endfor %}>
911

10-
{% for fileName, file in doc.example.files %}
11-
<div class="runnable-example-file" {% for attrName, attrValue in file.attributes %}
12-
{$ attrName $}="{$ attrValue $}"{% endfor %}>
13-
{% code -%}
14-
{$ file.fileContents $}
15-
{%- endcode %}
16-
</div>
17-
{% endfor %}
12+
{% for fileName, file in doc.example.files %}
13+
<div class="runnable-example-file" {% for attrName, attrValue in file.attributes %}
14+
{$ attrName $}="{$ attrValue $}"{% endfor %}>
15+
{% code -%}
16+
{$ file.fileContents $}
17+
{%- endcode %}
18+
</div>
19+
{% endfor %}
1820

19-
<iframe class="runnable-example-frame" src="{$ doc.example.deployments.default.outputPath $}" name="{$ doc.example.id $}"></iframe>
21+
<iframe class="runnable-example-frame" src="{$ doc.example.deployments.default.outputPath $}" name="{$ doc.example.id $}"></iframe>
22+
</div>
2023
</div>
2124

22-
23-
{# Be aware that we need these extra new lines here or marked will not realise that the <div>
24-
above is HTML and wrap each line in a <p> - thus breaking the HTML #}
25+
{# Be aware that we need these extra new lines here or marked will not realize that the <div>
26+
above is HTML and wrap each line in a <p> - thus breaking the HTML #}

‎docs/config/templates/git/api/api.template.html

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
{% extends "base.template.html" %}
2+
{% import "lib/deprecated.html" as x -%}
23

34
{% block content %}
45

@@ -33,12 +34,7 @@ <h2 id="known-issues">Known Issues</h2>
3334
{% endfor -%}
3435
{% endif %}
3536

36-
{% if doc.deprecated %}
37-
<fieldset class="deprecated">
38-
<legend>Deprecated API</legend>
39-
{$ doc.deprecated| marked $}
40-
</fieldset>
41-
{% endif %}
37+
{$ x.deprecatedBlock(doc) $}
4238

4339
<div>
4440
{% block dependencies %}

‎docs/config/templates/ngdoc/api/api.template.html

Lines changed: 86 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,100 @@
11
{% extends "base.template.html" %}
22

33
{% block content %}
4+
<h1>
5+
{% if doc.title %}{$ doc.title | marked $}{% else %}{$ doc.name | code $}{% endif %}
6+
</h1>
47

5-
{% block header %}
6-
<header class="api-profile-header">
7-
<h1 class="api-profile-header-heading">{$ doc.name $}</h1>
8-
<ol class="api-profile-header-structure naked-list step-list">
9-
{% block related_components %}{% endblock %}
8+
<h2>Installation</h2>
9+
{% if doc.installation or doc.installation == '' %}
10+
{$ doc.installation | marked $}
11+
{% else %}
12+
13+
<p>First, get the file:</p>
14+
<ul>
15+
<li>
16+
<a href="https://developers.google.com/speed/libraries/devguide#angularjs">Google CDN</a> e.g.
17+
{% code %}"//ajax.googleapis.com/ajax/libs/angularjs/X.Y.Z/{$ doc.packageFile $}"{% endcode %}
18+
</li>
19+
<li>
20+
<a href="https://www.npmjs.com/">NPM</a> e.g.
21+
{% code %}npm install {$ doc.packageName $}@X.Y.Z{% endcode %}
22+
</li>
1023
<li>
11-
- {$ doc.docType $} in module {$ doc.moduleDoc.id | link(doc.moduleDoc.name, doc.moduleDoc) $}
24+
<a href="http://bower.io">Bower</a> e.g.
25+
{% code %}bower install {$ doc.packageName $}#X.Y.Z{% endcode %}
1226
</li>
13-
</ol>
14-
</header>
15-
{% endblock %}
27+
<li>
28+
<a href="https://code.angularjs.org/">code.angularjs.org</a>
29+
(discouraged for production use) e.g.
30+
{% code %}"//code.angularjs.org/X.Y.Z/{$ doc.packageFile $}"{% endcode %}
31+
</li>
32+
</ul>
33+
<p>where X.Y.Z is the AngularJS version you are running.</p>
1634

17-
{% block description %}
18-
<div class="api-profile-description">
19-
{$ doc.description | marked $}
20-
</div>
21-
{% endblock %}
35+
<p>Then, include {$ doc.packageFile | code $} in your HTML:</p>
2236

23-
{% if doc.knownIssues %}
24-
<h2 id="known-issues">Known Issues</h2>
25-
{% for issue in doc.knownIssues -%}
26-
<div class="known-issue">
27-
{$ issue | marked $}
28-
</div>
29-
{% endfor -%}
37+
{% code %}
38+
<script src="path/to/angular.js"></script>
39+
<script src="path/to/{$ doc.packageFile $}"></script>
40+
{% endcode %}
41+
42+
<p>Finally, load the module in your application by adding it as a dependent module:</p>
43+
{% code %}
44+
angular.module('app', ['{$ doc.name $}']);
45+
{% endcode %}
46+
47+
<p>With that you&apos;re ready to get started!</p>
3048
{% endif %}
3149

32-
{% if doc.deprecated %}
33-
<fieldset class="deprecated">
34-
<legend>Deprecated API</legend>
35-
{$ doc.deprecated| marked $}
36-
</fieldset>
50+
{$ doc.description | marked $}
51+
52+
{% if doc.knownIssueDocs %}
53+
<div class="known-issues">
54+
<h2 id="known-issues">Known Issues</h2>
55+
<table class="definition-table">
56+
<tr><th>Name</th><th>Description</th></tr>
57+
{% for issueDoc in doc.knownIssueDocs -%}
58+
<tr>
59+
<td>{$ issueDoc.id | link(issueDoc.name, issueDoc) $}</td>
60+
<td>
61+
{% for issue in issueDoc.knownIssues -%}
62+
{$ issue | marked $} {% if not loop.last %}<hr>{% endif %}
63+
{% endfor -%}
64+
</td>
65+
</tr>
66+
{% endfor -%}
67+
</table>
68+
</div>
3769
{% endif %}
3870

39-
<div>
40-
{% block dependencies %}
41-
{%- if doc.requires %}
42-
<h2 id="dependencies">Dependencies</h2>
43-
<ul>
44-
{% for require in doc.requires %}<li>{$ require | link $}</li>{% endfor %}
45-
</ul>
46-
{% endif -%}
47-
{% endblock %}
48-
49-
{% block additional %}
50-
{% endblock %}
51-
52-
{% block examples %}
53-
{%- if doc.examples %}
54-
<h2 id="example">Example</h2>
55-
{%- for example in doc.examples -%}
56-
{$ example | marked $}
57-
{%- endfor -%}
58-
{% endif -%}
59-
{% endblock %}
71+
72+
{% if doc.componentGroups.length %}
73+
<div class="component-breakdown">
74+
<h2>Module Components</h2>
75+
{% for componentGroup in doc.componentGroups %}
76+
<div>
77+
<h3 class="component-heading" id="{$ componentGroup.groupType | dashCase $}">{$ componentGroup.groupType | title $}</h3>
78+
<table class="definition-table">
79+
<tr>
80+
<th>Name</th>
81+
<th>Description</th>
82+
</tr>
83+
{% for component in componentGroup.components %}
84+
<tr>
85+
<td>{$ component.id | link(component.name, component) $}</td>
86+
<td>{$ component.description | firstParagraph | marked $}</td>
87+
</tr>
88+
{% endfor %}
89+
</table>
90+
</div>
91+
{% endfor %}
6092
</div>
93+
{% endif %}
94+
95+
{% if doc.usage %}
96+
<h2>Usage</h2>
97+
{$ doc.usage | marked $}
98+
{% endif %}
6199

62-
{% endblock %}
100+
{% endblock %}

‎docs/config/templates/ngdoc/api/module.template.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ <h2>Installation</h2>
1111
<p>First include {$ doc.packageFile | code $} in your HTML:</p>
1212

1313
{% code %}
14-
<script src="angular.js">
15-
<script src="{$ doc.packageFile $}">
14+
<script src="angular.js"></script>
15+
<script src="{$ doc.packageFile $}"></script>
1616
{% endcode %}
1717

1818
<p>You can download this file from the following places:</p>

‎docs/config/templates/ngdoc/lib/deprecated.html

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{% macro deprecatedBlock(doc) %}{% if doc.deprecated %}
2+
<div class="alert alert-danger deprecation">
3+
<div class="title"><strong>Deprecated:</strong>
4+
{% if doc.deprecated.sinceVersion %}<span class="since">(since {$ doc.deprecated.sinceVersion $}) </span>{% endif %}
5+
{% if doc.deprecated.removeVersion %}<span class="remove">(to be removed in {$ doc.deprecated.removeVersion $}) </span>{% endif %}
6+
</div>
7+
{$ doc.deprecated.description | marked $}
8+
</div>
9+
{% endif %}{% endmacro %}

‎docs/config/templates/ngdoc/lib/events.template.html

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,16 @@
11
{% import "lib/macros.html" as lib -%}
2+
{% import "lib/deprecated.html" as x -%}
3+
24
{%- if doc.events %}
35
<h2>Events</h2>
46
<ul class="events">
57
{%- for event in doc.events %}
68
<li id="{$ event.name $}">
79
<h3>{$ event.name $}</h3>
810
<div>{$ event.description | marked $}</div>
11+
12+
{$ x.deprecatedBlock(event) $}
13+
914
{%- if event.eventType == 'listen' %}
1015
<div class="inline">
1116
<h4>Listen on: {$ event.eventTarget $}</h4>

‎docs/config/templates/ngdoc/lib/macros.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
{%- macro directiveParam(name, type, join, sep) %}
3737
{%- if type.optional %}[{% endif -%}
3838
{$ name | dashCase $}{$ join $}{$ type.name $}{$ sep $}
39-
{%- if type.optional %}]{% endif -%}
39+
{%- if type.optional %}]{% endif -%}
4040
{% endmacro -%}
4141

4242
{%- macro functionSyntax(fn) %}

0 commit comments

Comments
 (0)