Mark deprecated API properties with strike-out font

📚 Docs or angular.io bug report

Description

The API docs show many deprecated elements with strike-out font. Within classes and interfaces, deprecated methods are correctly struck out, but deprecated properties are not.

🔬 Minimal Reproduction

See https://angular.io/api/router/NavigationExtras#preserveQueryParams (deprecated in favor of queryParamsHandling since v4.

What's the affected URL?**

https://angular.io/api/router/NavigationExtras#preserveQueryParams
(might be more)

Expected vs Actual Behavior**

The deprecated property should appear in strike-out font.

These member objects are generated by other parts of the dgeni system (primarily by parsing the TS code and JSDOC comments - but also modified by other dgeni processors).

The good news is that any member that is marked as deprecated with have a property on them: member.deprecated. You can then use this in the templates to render them appropriately.

For example:

{%- macro renderMembers(doc) -%}
  {%- for member in doc.staticProperties %}{% if not member.internal %}
  <a class="code-anchor{% if member.deprecated %} deprecated-api-item{% endif %}" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor -%}
  {% for member in doc.staticMethods %}{% if not member.internal %}
  <a class="code-anchor{% if member.deprecated %} deprecated-api-item{% endif %}" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor -%}
  {% if doc.constructorDoc and not doc.constructorDoc.internal %}
  <a class="code-anchor{% if member.deprecated %} deprecated-api-item{% endif %}" href="{$ doc.path $}#{$ doc.constructorDoc.anchor | urlencode $}">{$ renderMemberSyntax(doc.constructorDoc, 1) $}</a>{% endif -%}
  {% for member in doc.properties %}{% if not member.internal %}
  <a class="code-anchor{% if member.deprecated %} deprecated-api-item{% endif %}" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor -%}
  {% for member in doc.methods %}{% if not member.internal %}
  <a class="code-anchor{% if member.deprecated %} deprecated-api-item{% endif %}" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor -%}

  {%- for ancestor in doc.extendsClauses %}{% if ancestor.doc %}

  // inherited from <a class="code-anchor" href="{$ ancestor.doc.path $}">{$ ancestor.doc.id $}</a>{$ renderMembers(ancestor.doc) $}{% endif %}{% endfor -%}
{%- endmacro -%}

Note here that I have added {% if member.deprecated %} deprecated-api-item{% endif %} to cause the deprecated-api-item CSS class to be added to any of the members that have this member.deprecated property. This will fix the "overview" section:

But you would need to look further through the templates to fix other areas where member get rendered, such as

angular/aio/tools/transforms/templates/api/lib/memberHelpers.html

Lines 178 to 188 in 382d3ed

    
           {%- macro renderMethodDetails(versionInfo, methods, containerClass, itemClass, headingText) -%} 
        
           {% set nonInternalMethods = methods | filterByPropertyValue('internal', undefined) %} 
        
           {% if nonInternalMethods.length %} 
        
           <section class="{$ containerClass $}"> 
        
             <h2>{$ headingText $}</h2> 
        
             {% for member in nonInternalMethods %} 
        
               {$ renderMethodDetail(versionInfo, member, itemClass) $} 
        
             {% endfor %} 
        
           </section> 
        
           {% endif %} 
        
           {%- endmacro -%}

and

angular/aio/tools/transforms/templates/api/lib/memberHelpers.html

Lines 191 to 230 in 382d3ed

    
           {%- macro renderProperties(properties, containerClass, propertyClass, headingText, headings, headingLevel = 2) -%} 
        
           {% set nonInternalProperties = properties | filterByPropertyValue('internal', undefined) %} 
        
           {% if nonInternalProperties.length -%} 
        
           <section class="{$ containerClass $}"> 
        
             <h{$ headingLevel $}>{$ headingText $}</h{$ headingLevel $}> 
        
             <table class="is-full-width list-table property-table"> 
        
               <thead> 
        
                 <tr> 
        
                   <th>{$ headings[0] or 'Property' $}</th> 
        
                   <th>{$ headings[1] or 'Description' $}</th> 
        
                 </tr> 
        
               </thead> 
        
               <tbody> 
        
               {% for property in nonInternalProperties %} 
        
                 <tr class="{$ propertyClass $}"> 
        
                   <td> 
        
                     <a id="{$ property.anchor $}"></a> 
        
                     <code>{$ renderMemberSyntax(property) $}</code> 
        
                   </td> 
        
                   <td> 
        
                     {%- if (property.isGetAccessor or property.isReadonly) and not property.isSetAccessor %}<span class='read-only-property'>Read-Only</span>{% endif %} 
        
                     {%- if property.isSetAccessor and not property.isGetAccessor %}<span class='write-only-property'>Write-Only</span>{% endif %} 
        
                     {% if property.constructorParamDoc %} <span class='from-constructor'>Declared in Constructor</span>{% endif %} 
        
                     {% if property.shortDescription %}{$ property.shortDescription | marked $}{% endif %} 
        
                     {$ (property.description or property.constructorParamDoc.description) | marked $} 
        
                     {%- if property.see.length %} 
        
                     <p>See also:</p> 
        
                     <ul> 
        
                     {% for see in property.see %} 
        
                       <li>{$ see | marked $}</li>{% endfor %} 
        
                     </ul> 
        
                     {% endif %} 
        
                     </td> 
        
               </tr> 
        
               {% endfor %} 
        
               </tbody> 
        
             </table> 
        
           </section> 
        
           {%- endif -%} 
        
           {%- endmacro -%}

docs: add deprecated-api-item class to deprecated items

docs: add deprecated-api-item class to deprecated items (#34088)

fix(docs-infra): add deprecated-api-item class to remaining deprecate…

@petebacondarwin

@petebacondarwin The Deprecated filter doesn't work with the Package type.
https://next.angular.io/api?status=deprecated&type=package

@jbogarthyde

@jbogarthyde - yes this was intentionally done in 234661b

See #25708

We may want to revisit this and work out some way of identifying whole packages that are deprecated, which I don't think we can currently do.

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

Navigation Menu

Repository navigation

Mark deprecated API properties with strike-out font #31455

📚 Docs or angular.io bug report

Description

🔬 Minimal Reproduction

What's the affected URL?**

Expected vs Actual Behavior**

6 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	{%- macro renderMethodDetails(versionInfo, methods, containerClass, itemClass, headingText) -%}
	{% set nonInternalMethods = methods \| filterByPropertyValue('internal', undefined) %}
	{% if nonInternalMethods.length %}
	<section class="{$ containerClass $}">
	<h2>{$ headingText $}</h2>
	{% for member in nonInternalMethods %}
	{$ renderMethodDetail(versionInfo, member, itemClass) $}
	{% endfor %}
	</section>
	{% endif %}
	{%- endmacro -%}

	{%- macro renderProperties(properties, containerClass, propertyClass, headingText, headings, headingLevel = 2) -%}
	{% set nonInternalProperties = properties \| filterByPropertyValue('internal', undefined) %}
	{% if nonInternalProperties.length -%}
	<section class="{$ containerClass $}">
	<h{$ headingLevel $}>{$ headingText $}</h{$ headingLevel $}>
	<table class="is-full-width list-table property-table">
	<thead>
	<tr>
	<th>{$ headings[0] or 'Property' $}</th>
	<th>{$ headings[1] or 'Description' $}</th>
	</tr>
	</thead>
	<tbody>
	{% for property in nonInternalProperties %}
	<tr class="{$ propertyClass $}">
	<td>
	<a id="{$ property.anchor $}"></a>
	<code>{$ renderMemberSyntax(property) $}</code>
	</td>
	<td>
	{%- if (property.isGetAccessor or property.isReadonly) and not property.isSetAccessor %}<span class='read-only-property'>Read-Only</span>{% endif %}
	{%- if property.isSetAccessor and not property.isGetAccessor %}<span class='write-only-property'>Write-Only</span>{% endif %}
	{% if property.constructorParamDoc %} <span class='from-constructor'>Declared in Constructor</span>{% endif %}
	{% if property.shortDescription %}{$ property.shortDescription \| marked $}{% endif %}
	{$ (property.description or property.constructorParamDoc.description) \| marked $}
	{%- if property.see.length %}
	<p>See also:</p>
	<ul>
	{% for see in property.see %}
	<li>{$ see \| marked $}</li>{% endfor %}
	</ul>
	{% endif %}
	</td>
	</tr>
	{% endfor %}
	</tbody>
	</table>
	</section>
	{%- endif -%}
	{%- endmacro -%}

Mark deprecated API properties with strike-out font #31455

Description

📚 Docs or angular.io bug report

Description

🔬 Minimal Reproduction

What's the affected URL?**

Expected vs Actual Behavior**

Activity

6 remaining items

petebacondarwin commented on Nov 27, 2019

jbogarthyde commented on Dec 10, 2019

petebacondarwin commented on Dec 11, 2019

angular-automatic-lock-bot commented on Jan 11, 2020

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions