deprecate "attr" in favor of "property"

markstory · Aug 3, 2023 · f395c49 · f395c49
1 parent d9a8ba5
commit f395c49
Show file tree

Hide file tree

Showing 5 changed files with 75 additions and 65 deletions.
diff --git a/README.rst b/README.rst
@@ -28,10 +28,10 @@ PHP Domain supports following objects:
 
 .. note::
 
-   This domain expresses methods and attribute names like this::
+   This domain expresses methods and properties like this::
 
       Class::method_name
-      Class::$attribute_name
+      Class::$prop_name
 
    You address classes/functions in namespaces using \\ syntax as you would in PHP::
 

diff --git a/doc/reference.rst b/doc/reference.rst
@@ -103,7 +103,7 @@ Each directive populates the index, and or the namespace index.
 
 .. rst:directive:: .. php:class:: name
 
-   Describes a class.  Methods, attributes, and constants belonging to the class
+   Describes a class.  Methods, properties, and constants belonging to the class
    should be inside this directive's body::
 
         .. php:class:: MyClass
@@ -115,7 +115,7 @@ Each directive populates the index, and or the namespace index.
            Method description
 
 
-   Attributes, methods and constants don't need to be nested.  They can also just 
+   Properties, methods and constants don't need to be nested.  They can also just 
    follow the class declaration::
 
         .. php:class:: MyClass
@@ -128,7 +128,7 @@ Each directive populates the index, and or the namespace index.
         
 
    .. seealso:: :rst:dir:`php:method`
-                :rst:dir:`php:attr`
+                :rst:dir:`php:property`
                 :rst:dir:`php:const`
 
 .. rst:directive:: .. php:method:: name(signature)
@@ -145,9 +145,9 @@ Each directive populates the index, and or the namespace index.
         
            This is an instance method.
 
-.. rst:directive:: .. php:attr:: name
+.. rst:directive:: .. php:property:: name
 
-   Describe an property/attribute on a class.
+   Describe a property on a class.
 
 Cross Referencing
 =================
@@ -192,11 +192,11 @@ matching directive is found:
    
      :php:method:`DateTime::setDate`
 
-.. rst:role:: php:attr
+.. rst:role:: php:property
 
    Reference a property on an object::
    
-      :php:attr:`ClassName::$propertyName`
+      :php:property:`ClassName::$propertyName`
 
 .. rst:role:: php:interface
 

diff --git a/sphinxcontrib/phpdomain.py b/sphinxcontrib/phpdomain.py
@@ -77,6 +77,7 @@ def throw_if_false(fromdocnode, value, message: str):
     "exception": None,
     "method": "::",
     "const": "::",
+    "property": "::$",
     "attr": "::$",
     "staticmethod": "::",
     "case": "::",
@@ -365,7 +366,8 @@ def _toc_entry_name(self, sig_node: addnodes.desc_signature) -> str:
             return name + parens
         if config.toc_object_entries_show_parents == "all":
             if (
-                objtype in {"method", "const", "attr", "staticmethod", "case"}
+                objtype
+                in {"method", "const", "property", "attr", "staticmethod", "case"}
                 and len(parents) > 0
             ):
                 name = parents.pop() + "::" + name
@@ -379,7 +381,11 @@ def get_index_text(self, namespace, name):
         raise NotImplementedError("must be implemented in subclasses")
 
     def _is_class_member(self):
-        return self.objtype.startswith("method") or self.objtype.startswith("attr")
+        return (
+            self.objtype.startswith("method")
+            or self.objtype.startswith("property")
+            or self.objtype.startswith("attr")
+        )
 
     def add_target_and_index(self, name_cls, sig, signode):
         if self.objtype == "global":
@@ -511,7 +517,7 @@ class PhpClassmember(PhpObject):
     """
 
     def get_signature_prefix(self, sig):
-        if self.objtype == "attr":
+        if self.objtype == "property" or self.objtype == "attr":
             return _("property ")
         if self.objtype == "staticmethod":
             return _("static ")
@@ -527,6 +533,7 @@ def get_index_text(self, namespace, name_cls):
 
         if (
             self.objtype.endswith("method")
+            or self.objtype == "property"
             or self.objtype == "attr"
             or self.objtype == "case"
         ):
@@ -543,7 +550,7 @@ def get_index_text(self, namespace, name_cls):
                 return _("%s() (%s\\%s method)") % (propname, namespace, clsname)
             else:
                 return _("%s() (%s method)") % (propname, clsname)
-        elif self.objtype == "attr":
+        elif self.objtype == "property" or self.objtype == "attr":
             if namespace and clsname is None:
                 return _("%s (in namespace %s)") % (name, namespace)
             elif namespace and self.env.config.add_module_names:
@@ -749,6 +756,7 @@ class PhpDomain(Domain):
         "const": ObjType(_("const"), "const", "obj"),
         "method": ObjType(_("method"), "method", "obj"),
         "class": ObjType(_("class"), "class", "obj"),
+        "property": ObjType(_("attribute"), "property", "obj"),
         "attr": ObjType(_("attribute"), "attr", "obj"),
         "exception": ObjType(_("exception"), "exc", "obj"),
         "namespace": ObjType(_("namespace"), "namespace", "obj"),
@@ -765,7 +773,8 @@ class PhpDomain(Domain):
         "class": PhpClasslike,
         "method": PhpClassmember,
         "staticmethod": PhpClassmember,  # deprecated, use "method" with "static" modifier, methods in PHP are exclusively static or non-static
-        "attr": PhpClassmember,
+        "property": PhpClassmember,
+        "attr": PhpClassmember,  # deprecated, use "property"
         "case": PhpClassmember,
         "exception": PhpClasslike,  # deprecated, use "class", exceptions in PHP are regular classes
         "interface": PhpClasslike,
@@ -784,6 +793,7 @@ class PhpDomain(Domain):
         "exc": PhpXRefRole(),
         "method": PhpXRefRole(fix_parens=False),
         "meth": PhpXRefRole(fix_parens=False),  # deprecated, use "method"
+        "property": PhpXRefRole(),
         "attr": PhpXRefRole(),
         "const": PhpXRefRole(),
         "namespace": PhpXRefRole(),

diff --git a/test/rst_doc.html b/test/rst_doc.html
@@ -174,18 +174,18 @@ <h2>Classes<a class="headerlink" href="#classes" title="Permalink to this headin
               <p>Y-m-dTH:i:sP</p>
             </dd>
           </dl>
-          <dl class="php attr">
-            <dt class="sig sig-object php" id="DateTime::$testattr">
+          <dl class="php property">
+            <dt class="sig sig-object php" id="DateTime::$testprop">
               <em class="property">
                 <span class="pre">property</span>
               </em>
               <span class="sig-name descname">
-                <span class="pre">testattr</span>
+                <span class="pre">testprop</span>
               </span>
-              <a class="headerlink" href="#DateTime::$testattr" title="Permalink to this definition">&#xB6;</a>
+              <a class="headerlink" href="#DateTime::$testprop" title="Permalink to this definition">&#xB6;</a>
             </dt>
             <dd>
-              <p>Value of some attribute</p>
+              <p>Value of some property</p>
             </dd>
           </dl>
         </dd>
@@ -210,21 +210,21 @@ <h2>Classes<a class="headerlink" href="#classes" title="Permalink to this headin
           <p>Update something.</p>
         </dd>
       </dl>
-      <dl class="php attr">
-        <dt class="sig sig-object php" id="OtherClass::$nonIndentedAttribute">
+      <dl class="php property">
+        <dt class="sig sig-object php" id="OtherClass::$nonIndentedProperty">
           <em class="property">
             <span class="pre">property</span>
           </em>
           <span class="sig-prename descclassname">
             <span class="pre">OtherClass::$</span>
           </span>
           <span class="sig-name descname">
-            <span class="pre">nonIndentedAttribute</span>
+            <span class="pre">nonIndentedProperty</span>
           </span>
-          <a class="headerlink" href="#OtherClass::$nonIndentedAttribute" title="Permalink to this definition">&#xB6;</a>
+          <a class="headerlink" href="#OtherClass::$nonIndentedProperty" title="Permalink to this definition">&#xB6;</a>
         </dt>
         <dd>
-          <p>This attribute wasn&#x2019;t indented</p>
+          <p>This property wasn&#x2019;t indented</p>
         </dd>
       </dl>
       <dl class="php const">
@@ -338,18 +338,18 @@ <h2>Interfaces<a class="headerlink" href="#interfaces" title="Permalink to this
               <p>Y-m-dTH:i:sP</p>
             </dd>
           </dl>
-          <dl class="php attr">
-            <dt class="sig sig-object php" id="DateTimeInterface::$testattr">
+          <dl class="php property">
+            <dt class="sig sig-object php" id="DateTimeInterface::$testprop">
               <em class="property">
                 <span class="pre">property</span>
               </em>
               <span class="sig-name descname">
-                <span class="pre">testattr</span>
+                <span class="pre">testprop</span>
               </span>
-              <a class="headerlink" href="#DateTimeInterface::$testattr" title="Permalink to this definition">&#xB6;</a>
+              <a class="headerlink" href="#DateTimeInterface::$testprop" title="Permalink to this definition">&#xB6;</a>
             </dt>
             <dd>
-              <p>Value of some attribute</p>
+              <p>Value of some property</p>
             </dd>
           </dl>
         </dd>
@@ -484,9 +484,9 @@ <h3>Test Case - Global symbols with no namespaces<a class="headerlink" href="#te
           </a>
         </p>
         <p>
-          <a class="reference internal" href="#DateTime::$testattr" title="DateTime::$testattr">
-            <code class="xref php php-attr docutils literal notranslate">
-              <span class="pre">DateTime::$testattr</span>
+          <a class="reference internal" href="#DateTime::$testprop" title="DateTime::$testprop">
+            <code class="xref php php-property docutils literal notranslate">
+              <span class="pre">DateTime::$testprop</span>
             </code>
           </a>
         </p>
@@ -498,9 +498,9 @@ <h3>Test Case - Global symbols with no namespaces<a class="headerlink" href="#te
           </a>
         </p>
         <p>
-          <a class="reference internal" href="#OtherClass::$nonIndentedAttribute" title="OtherClass::$nonIndentedAttribute">
-            <code class="xref php php-attr docutils literal notranslate">
-              <span class="pre">OtherClass::$nonIndentedAttribute</span>
+          <a class="reference internal" href="#OtherClass::$nonIndentedProperty" title="OtherClass::$nonIndentedProperty">
+            <code class="xref php php-property docutils literal notranslate">
+              <span class="pre">OtherClass::$nonIndentedProperty</span>
             </code>
           </a>
         </p>
@@ -547,9 +547,9 @@ <h3>Test Case - Global symbols with no namespaces<a class="headerlink" href="#te
           </a>
         </p>
         <p>
-          <a class="reference internal" href="#DateTimeInterface::$testattr" title="DateTimeInterface::$testattr">
-            <code class="xref php php-attr docutils literal notranslate">
-              <span class="pre">DateTimeInterface::$testattr</span>
+          <a class="reference internal" href="#DateTimeInterface::$testprop" title="DateTimeInterface::$testprop">
+            <code class="xref php php-property docutils literal notranslate">
+              <span class="pre">DateTimeInterface::$testprop</span>
             </code>
           </a>
         </p>
@@ -586,9 +586,9 @@ <h3>Test Case - Prefix less links<a class="headerlink" href="#test-case-prefix-l
           </a>
         </p>
         <p>
-          <a class="reference internal" href="#DateTime::$testattr" title="DateTime::$testattr">
-            <code class="xref php php-attr docutils literal notranslate">
-              <span class="pre">$testattr</span>
+          <a class="reference internal" href="#DateTime::$testprop" title="DateTime::$testprop">
+            <code class="xref php php-property docutils literal notranslate">
+              <span class="pre">$testprop</span>
             </code>
           </a>
         </p>
@@ -678,7 +678,7 @@ <h2>Namespaced elements<a class="headerlink" href="#namespace-LibraryName" title
               <p>Test constant</p>
             </dd>
           </dl>
-          <dl class="php attr">
+          <dl class="php property">
             <dt class="sig sig-object php" id="LibraryName\LibraryClass::$property">
               <em class="property">
                 <span class="pre">property</span>
@@ -717,7 +717,7 @@ <h2>Namespaced elements<a class="headerlink" href="#namespace-LibraryName" title
           <p>A normal instance method.</p>
         </dd>
       </dl>
-      <dl class="php attr">
+      <dl class="php property">
         <dt class="sig sig-object php" id="LibraryName\NamespaceClass::$property">
           <em class="property">
             <span class="pre">property</span>
@@ -944,7 +944,7 @@ <h3>Test Case - not including namespace<a class="headerlink" href="#test-case-no
         </p>
         <p>
           <a class="reference internal" href="#LibraryName\LibraryClass::$property" title="LibraryName\LibraryClass::$property">
-            <code class="xref php php-attr docutils literal notranslate">
+            <code class="xref php php-property docutils literal notranslate">
               <span class="pre">LibraryClass::$property</span>
             </code>
           </a>
@@ -979,7 +979,7 @@ <h3>Test Case - not including namespace<a class="headerlink" href="#test-case-no
         </p>
         <p>
           <a class="reference internal" href="#LibraryName\NamespaceClass::$property" title="LibraryName\NamespaceClass::$property">
-            <code class="xref php php-attr docutils literal notranslate">
+            <code class="xref php php-property docutils literal notranslate">
               <span class="pre">NamespaceClass::$property</span>
             </code>
           </a>
@@ -1110,7 +1110,7 @@ <h3>Test Case - Links with prefix trimming<a class="headerlink" href="#test-case
         </p>
         <p>
           <a class="reference internal" href="#LibraryName\LibraryClass::$property" title="LibraryName\LibraryClass::$property">
-            <code class="xref php php-attr docutils literal notranslate">
+            <code class="xref php php-property docutils literal notranslate">
               <span class="pre">$property</span>
             </code>
           </a>
@@ -1155,12 +1155,12 @@ <h3>Test Case - global access<a class="headerlink" href="#test-case-global-acces
         </p>
         <p>
           <a class="reference internal" href="#LibraryName\LibraryClass::$property" title="LibraryName\LibraryClass::$property">
-            <code class="xref php php-attr docutils literal notranslate">
+            <code class="xref php php-property docutils literal notranslate">
               <span class="pre">LibraryName\LibraryClass::$property</span>
             </code>
           </a>
         </p>
-        <p><a class="reference internal" href="#LibraryName\LibraryClass::$property" title="LibraryName\LibraryClass::$property"><code class="xref php php-attr docutils literal notranslate"><span class="pre">$property</span></code></a> Should not be prefixed with classname.</p>
+        <p><a class="reference internal" href="#LibraryName\LibraryClass::$property" title="LibraryName\LibraryClass::$property"><code class="xref php php-property docutils literal notranslate"><span class="pre">$property</span></code></a> Should not be prefixed with classname.</p>
         <p>
           <a class="reference internal" href="#LibraryName\LibraryClass::TEST_CONST" title="LibraryName\LibraryClass::TEST_CONST">
             <code class="xref php php-const docutils literal notranslate">