feat(doc): adding support for @Changed and @deprecated

SuperFola · SuperFola · commit e8ee48f16464 · 2026-01-01T18:02:59.000+01:00
diff --git a/README.md b/README.md
@@ -27,8 +27,10 @@ python3 -m arkdoc --help
 ## Syntax
 
 - `@brief <description>`: a single brief declaration is expected
-- `@param <name> <description>`: multiple `@param` declaration can be written
+- `@param <name> <description>`: multiple `@param` declarations can be written
 - `@details <description>`: a single detailed declaration is expected
+- `@deprecated <description>`: an optional deprecation notice
+- `@changed <version> <description>`: multiple `@changed` declarations can be written. Creates an optional change list to document when and how a function changed
 - `=begin` / code block / `=end`: a single code block (it can contain multiple lines) is expected
 - `@author <url>,<url>,...`: the url to the profiles of the authors must be separated by commas, spaces can be added
 - any line not starting with a `@<keyword>` will be ignored, unless it is enclosed in a `=begin`/`=end` block
diff --git a/arkdoc/generator/base.py b/arkdoc/generator/base.py
@@ -56,7 +56,7 @@ def _create_files_list(self, parsers: List[Parser]):
     def generate_index(self):
         raise NotImplementedError
 
-    def generate_sections(self, functions: List[spec.Function], with_hr: bool=False):
+    def generate_sections(self, functions: List[spec.Function], with_hr: bool = False):
         sections = ""
 
         for func in functions:
@@ -84,10 +84,38 @@ def generate_sections(self, functions: List[spec.Function], with_hr: bool=False)
                 if func.desc.params
                 else ""
             )
+            maybe_deprecated_notice = (
+                self.formatter.div(
+                    self.formatter.b("Deprecated"),
+                    ": ",
+                    func.desc.deprecation_notice,
+                    self.formatter.new_line()
+                )
+                if func.desc.deprecation_notice
+                else ""
+            )
+            maybe_changelists = (
+                self.formatter.div(
+                    self.formatter.b("Changes"),
+                    ":",
+                    self.formatter.new_line(),
+                    self.formatter.ul(
+                        [
+                            f"{self.formatter.b(c.version)}: {c.desc}"
+                            for c in sorted(func.desc.changelist, key=lambda change: change.version, reverse=True)
+                        ]
+                    ),
+                    self.formatter.new_line()
+                )
+                if func.desc.changelist
+                else ""
+            )
             content = self.formatter.div(
                 self.formatter.div(self.formatter.inline_code(func.signature)),
                 self.formatter.div(func.desc.brief),
                 self.formatter.new_line(),
+                maybe_deprecated_notice,
+                maybe_changelists,
                 self.formatter.div(self.formatter.b("Note"), ": ", func.desc.details) if func.desc.details else "",
                 self.formatter.new_line(),
                 authors,
diff --git a/arkdoc/generator/specification.py b/arkdoc/generator/specification.py
@@ -15,13 +15,21 @@ class Param:
     desc: str
 
 
+@dataclass
+class Change:
+    version: str
+    desc: str
+
+
 @dataclass
 class Description:
     brief: str
     details: str
     params: List[Param]
     code: str
     authors: List[str]
+    deprecation_notice: str
+    changelist: List[Change]
 
 
 @dataclass
diff --git a/arkdoc/generator/utils.py b/arkdoc/generator/utils.py
@@ -2,11 +2,21 @@
 
 import re
 from typing import Tuple, Dict
+from copy import deepcopy
 
 from . import specification as spec
 from ..parser import Documentation, Source
 from .. import logger
 
+DEFAULT_KEYS = {
+    "brief": "",
+    "details": "",
+    "param": [],
+    "author": "",
+    "deprecated": "",
+    "changed": []
+}
+
 
 def extractor(data: Dict, doc: Documentation) -> Tuple[Dict, str]:
     in_code = False
@@ -42,42 +52,54 @@ def extractor(data: Dict, doc: Documentation) -> Tuple[Dict, str]:
         for i, param in enumerate(data["param"]):
             param_name, desc = param.split(" ", 1)
             data["param"][i] = spec.Param(param_name, desc)
+    if "changed" in data:
+        for i, changed in enumerate(data["changed"]):
+            version, desc = changed.split(" ", 1)
+            data["changed"][i] = spec.Change(version, desc)
     if "author" in data:
         data["author"] = [el.strip() for el in data["author"].split(",") if data["author"]]
 
     return data, "\n".join(code)
 
 
+def describe(data: Dict, code: str) -> spec.Description:
+    return spec.Description(
+        brief=data["brief"],
+        details=data["details"],
+        params=data["param"],
+        code=code,
+        authors=data["author"],
+        deprecation_notice=data["deprecated"],
+        changelist=data["changed"]
+    )
+
+
 def from_ark(doc: Documentation) -> spec.Function:
     _, name, args = doc.signature()
-    data, code = extractor({"brief": "", "details": "", "param": [], "author": ""}, doc)
+    data, code = extractor(deepcopy(DEFAULT_KEYS), doc)
 
     if args is not None and len(data["param"]) != len(args):
         logger.warn(
-            f"Function {name} was defined with {len(args)} arguments, "
+            f"Function {name} was defined with {len(args)} argument(s), "
             f"but {len(data['param'])} are documented"
         )
 
     return spec.Function(
         name,
         doc.pretty_signature,
-        spec.Description(
-            data["brief"], data["details"], data["param"], code, data["author"]
-        ),
+        describe(data, code),
     )
 
 
 def from_cpp(doc: Documentation) -> spec.Function:
-    data, code = extractor(
-        {"name": "", "brief": "", "details": "", "param": [], "author": ""}, doc
-    )
+    parameters = {"name": ""}
+    parameters.update(deepcopy(DEFAULT_KEYS))
+    data, code = extractor(parameters, doc)
 
     return spec.Function(
         data["name"],
         f"Builtin ({data['name']} {' '.join(e.name for e in data['param'])})",
-        spec.Description(
-            data["brief"], data["details"], data["param"], code, data["author"]
-        ),
+        describe(data, code),
     )
 
 
