>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3193358. --> Reported by: [joachim](https://www.drupal.org/user/107701) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p><a href="https://www.drupal.org/docs/develop/standards/api-documentation-and-comment-standards#deprecated">https://www.drupal.org/docs/develop/standards/api-documentation-and-comment-standards#deprecated</a> doesn't say whether a @deprecated tag should or may include a link to a change record on drupal.org.</p> <p>This means that most of core seems to link to the CR in a separate @see. The problem with doing this is that api.d.org shows that in the separate 'See also' section, and it's not clear to the reader that this URL is more information specifically about the deprecation. </p> <p>See for example <a href="https://api.drupal.org/api/drupal/core%21includes%21database.inc/function/db_add_field/8.9.x">https://api.drupal.org/api/drupal/core%21includes%21database.inc/function/db_add_field/8.9.x</a></p> <p>Docs standards should additionally say that a CR should be linked to if one exists, and that the link must be given within the @deprecated tag.</p> <p>See for example <a href="https://api.drupal.org/api/drupal/core%21modules%21migrate_drupal%21src%21Plugin%21migrate%21FieldMigration.php/constant/FieldMigration%3A%3APLUGIN_METHOD/8.9.x">https://api.drupal.org/api/drupal/core%21modules%21migrate_drupal%21src%21Plugin%21migrate%21FieldMigration.php/constant/FieldMigration%3A%3APLUGIN_METHOD/8.9.x</a></p> <h3 id="summary-benefits">Benefits</h3> <p>It would be clearer when reading both api.d.o docs and code that the URL is directly related to the deprecation.</p> <h3 id="summary-supporters">Three supporters required</h3> <ol> <li><a href="https://www.drupal.org/u/">https://www.drupal.org/u/</a>{userid} (yyyy-mm-dd they added support)</li> <li><a href="https://www.drupal.org/u/">https://www.drupal.org/u/</a>{userid} (yyyy-mm-dd they added support)</li> <li><a href="https://www.drupal.org/u/">https://www.drupal.org/u/</a>{userid} (yyyy-mm-dd they added support)</li> </ol> <h3 id="summary-proposed-changes">Proposed changes</h3> <p>Provide all proposed changes to the Drupal <a href="https://www.drupal.org/docs/develop/standards">Coding standards</a>. Give a link to each section that will be changed, and show the current text and proposed text as in the following layout:</p> <h4>1. <a href="https://www.drupal.org/docs/develop/standards/php/api-documentation-and-comment-standards#deprecated">@deprecated: Indicating deprecated functionality</a></h4> <h5>Current text</h5> <blockquote><p>The <code class="language-php">@deprecated</code> tag is placed in a documentation block to indicate that a function, method, or class has been deprecated and should not be used, but has not yet been removed.</p> <p>Syntax</p> <pre> <div class="codeblock"><code class="language-php">@deprecated in %deprecation-version% and is removed from %removal-version%. %extra-info%.<br>@see %cr-link%<p>Syntax notes</p> <dl> <dt>%deprecation-version%</dt> <dd>The <strong>version string</strong> representing when the change occurred. <ul> <li>For Drupal core and contrib projects that use semantic versioning, the version string is: <ul> <li><code class="language-php">project:major.minor.patch</code> or</li> <li><code class="language-php">project:major.minor.patch-tag[n]</code></li> </ul> </li> <li>For contrib projects that use legacy core-compatibility-prefixed versioning, the version string is: <ul> <li><code class="language-php">project:8.x-minor.patch</code> or</li> <li><code class="language-php">project:8.x-minor.patch-tag[n]</code></li> </ul> </li> </ul> </dd> <dt>%removal-version%</dt> <dd>The <strong>version string</strong> representing when the deprecated code path will be removed.</dd> <dt>%extra-info%</dt> <dd>This is free text. Useful things to include are hints on how to correct the code, what replacement to use, etc.</dd> <dt>%cr-link%</dt> <dd>The link to the change record on drupal.org (for core deprecations) or the relevant issue.</dd> </dl> <h5>Proposed text</h5> <p>Change the syntax example to:</p> <blockquote><pre> <div class="codeblock"><code class="language-php">@deprecated in %deprecation-version% and is removed from %removal-version%. %extra-info%. See %cr-link%. <h4>2. Repeat the above for each page or sub-page that needs to be changed.</h4> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ol> <li><del>Create this issue in the Coding Standards queue, using the defined template</del></li> <li>Add supporters</li> <li>Create a Change Record</li> <li>Review by the Coding Standards Committee</li> <li>Coding Standards Committee takes action as required</li> <li>Discussed by the Core Committer Committee, if it impacts Drupal Core</li> <li>Final review by Coding Standards Committee</li> <li>Documentation updates <ol> <li>Edit all pages</li> <li>Publish change record</li> <li>Remove 'Needs documentation edits' tag</li> </ol> </li> <li>If applicable, create follow-up issues for PHPCS rules/sniffs changes</li> </ol> <p>For a full explanation of these steps see the <a href="https://www.drupal.org/project/coding_standards" title="Coding Standards project page">Coding Standards project page</a></p> </code></div></pre></blockquote></code></div></pre></blockquote>