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

Commit 08fce2d

Browse files
petebacondarwinpetebacondarwin
committed
chore(docs): deprecation notices for methods and properties
Closes #15351
1 parent 5886d06 commit 08fce2d

File tree

8 files changed

+124
-92
lines changed

8 files changed

+124
-92
lines changed

‎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/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/lib/deprecated.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{% macro deprecatedBlock(doc) %}{% if doc.deprecated %}
2+
<div class="alert alert-warning">
3+
<div class="deprecated-title">Deprecated:</div>
4+
{$ doc.deprecated| marked $}
5+
</div>
6+
{% 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) %}

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
{% import "lib/macros.html" as lib -%}
2+
{% import "lib/deprecated.html" as x -%}
3+
24
{%- if doc.methods %}
35
<h2>Methods</h2>
46
<ul class="methods">
@@ -7,6 +9,8 @@ <h2>Methods</h2>
79
<h3>{$ lib.functionSyntax(method) $}</h3>
810
<div>{$ method.description | marked $}</div>
911

12+
{$ x.deprecatedBlock(method) $}
13+
1014
{% if method.params %}
1115
<h4>Parameters</h4>
1216
{$ lib.paramTable(method.params) $}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
{% import "lib/macros.html" as lib -%}
2+
{% import "lib/deprecated.html" as x -%}
3+
24
{%- if doc.properties %}
35
<h2>Properties</h2>
46
<ul class="properties">
57
{%- for property in doc.properties %}
68
<li id="{$ property.name $}">
79
<h3>{$ property.name | code $}</h3>
810
{$ lib.typeInfo(property) $}
11+
{$ x.deprecatedBlock(property) $}
912
</li>
1013
{% endfor -%}
1114
</ul>

0 commit comments

Comments
 (0)