From f94ac4b05bdca3a9569172caf56254c7f965bfb5 Mon Sep 17 00:00:00 2001
From: Andrew Nicols <andrew@nicols.co.uk>
Date: Thu, 28 Mar 2024 09:18:58 +0800
Subject: [PATCH] Deprecated items do not need a description (#139)

---
 moodle/Sniffs/Commenting/DocblockDescriptionSniff.php       | 6 ++++++
 .../Commenting/fixtures/DocblockDescription/standard.php    | 5 +++++
 2 files changed, 11 insertions(+)

diff --git a/moodle/Sniffs/Commenting/DocblockDescriptionSniff.php b/moodle/Sniffs/Commenting/DocblockDescriptionSniff.php
index 330a87c..74028ea 100644
--- a/moodle/Sniffs/Commenting/DocblockDescriptionSniff.php
+++ b/moodle/Sniffs/Commenting/DocblockDescriptionSniff.php
@@ -79,6 +79,12 @@ public function process(File $phpcsFile, $stackPtr) {
             }
             $faultAtLine = $tokens[$stopAt]['line'];
 
+            $deprecatedTagPtrs = Docblocks::getMatchingDocTags($phpcsFile, $docblockPtr, '@deprecated');
+            if (count($deprecatedTagPtrs) > 0) {
+                // Skip if the docblock contains a @deprecated tag.
+                continue;
+            }
+
             // Skip to the next T_DOC_COMMENT_STAR line. We do not accept single line docblocks.
             $docblockLinePtr = $docblockPtr;
             while ($docblockLinePtr = $phpcsFile->findNext(T_DOC_COMMENT_STAR, $docblockLinePtr + 1, $stopAt)) {
diff --git a/moodle/Tests/Sniffs/Commenting/fixtures/DocblockDescription/standard.php b/moodle/Tests/Sniffs/Commenting/fixtures/DocblockDescription/standard.php
index 3400894..e0d3ac9 100644
--- a/moodle/Tests/Sniffs/Commenting/fixtures/DocblockDescription/standard.php
+++ b/moodle/Tests/Sniffs/Commenting/fixtures/DocblockDescription/standard.php
@@ -58,3 +58,8 @@ trait trait_with_docblock_but_no_description {}
  * @license
  */
 function function_with_docblock_but_no_description() {}
+
+/**
+ * @deprecated
+ */
+function function_with_deprecated_tag() {}