From f395c493a01e94f7321f5ff6ec13e23d8ea13070 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20Vo=C5=99=C3=AD=C5=A1ek?= Date: Thu, 3 Aug 2023 18:47:48 +0200 Subject: [PATCH] deprecate "attr" in favor of "property" --- README.rst | 4 +-- doc/reference.rst | 14 ++++---- sphinxcontrib/phpdomain.py | 20 ++++++++--- test/rst_doc.html | 68 +++++++++++++++++++------------------- test/rst_doc.md | 34 +++++++++---------- 5 files changed, 75 insertions(+), 65 deletions(-) diff --git a/README.rst b/README.rst index 9407f786..f3c831df 100644 --- 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 index 31fb4d18..2a64babc 100644 --- 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 index ab2be1f9..1e65ec01 100644 --- 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 index 5a183538..bc3b949c 100644 --- a/test/rst_doc.html +++ b/test/rst_doc.html @@ -174,18 +174,18 @@

Classes -
+
+
property - testattr + testprop - +
-

Value of some attribute

+

Value of some property

@@ -210,8 +210,8 @@

Classes -
+
+
property @@ -219,12 +219,12 @@

ClassesOtherClass::$ - nonIndentedAttribute + nonIndentedProperty - +

-

This attribute wasn’t indented

+

This property wasn’t indented

@@ -338,18 +338,18 @@

Interfaces -
+
+
property - testattr + testprop - +
-

Value of some attribute

+

Value of some property

@@ -484,9 +484,9 @@

Test Case - Global symbols with no namespaces - - DateTime::$testattr + + + DateTime::$testprop

@@ -498,9 +498,9 @@

Test Case - Global symbols with no namespaces - - OtherClass::$nonIndentedAttribute + + + OtherClass::$nonIndentedProperty

@@ -547,9 +547,9 @@

Test Case - Global symbols with no namespaces - - DateTimeInterface::$testattr + + + DateTimeInterface::$testprop

@@ -586,9 +586,9 @@

Test Case - Prefix less links - - $testattr + + + $testprop

@@ -678,7 +678,7 @@

Namespaced elementsTest constant

-
+
property @@ -717,7 +717,7 @@

Namespaced elementsA normal instance method.

-
+
property @@ -944,7 +944,7 @@

Test Case - not including namespace - + LibraryClass::$property @@ -979,7 +979,7 @@

Test Case - not including namespace - + NamespaceClass::$property @@ -1110,7 +1110,7 @@

Test Case - Links with prefix trimming - + $property @@ -1155,12 +1155,12 @@

Test Case - global access - + LibraryName\LibraryClass::$property

-

$property Should not be prefixed with classname.

+

$property Should not be prefixed with classname.

diff --git a/test/rst_doc.md b/test/rst_doc.md index ccf37994..236c342d 100644 --- a/test/rst_doc.md +++ b/test/rst_doc.md @@ -59,9 +59,9 @@ Classes Y-m-d\TH:i:sP - .. php:attr:: testattr + .. php:property:: testprop - Value of some attribute + Value of some property .. php:class:: OtherClass @@ -71,9 +71,9 @@ Classes Update something. -.. php:attr:: nonIndentedAttribute +.. php:property:: nonIndentedProperty - This attribute wasn't indented + This property wasn't indented .. php:const:: NO_INDENT @@ -110,9 +110,9 @@ Interfaces Y-m-d\TH:i:sP - .. php:attr:: testattr + .. php:property:: testprop - Value of some attribute + Value of some property .. php:interface:: OtherInterface @@ -164,11 +164,11 @@ Test Case - Global symbols with no namespaces :php:const:`DateTime::ATOM` -:php:attr:`DateTime::$testattr` +:php:property:`DateTime::$testprop` :php:method:`OtherClass::update` -:php:attr:`OtherClass::$nonIndentedAttribute` +:php:property:`OtherClass::$nonIndentedProperty` :php:const:`OtherClass::NO_INDENT` @@ -182,7 +182,7 @@ Test Case - Global symbols with no namespaces :php:const:`DateTimeInterface::ATOM` -:php:attr:`DateTimeInterface::$testattr` +:php:property:`DateTimeInterface::$testprop` :php:interface:`OtherInterface` @@ -197,7 +197,7 @@ The following links should not be prefixed with a classname. :php:method:`~DateTime::setDate()` -:php:attr:`~DateTime::$testattr` +:php:property:`~DateTime::$testprop` Namespaced elements @@ -228,7 +228,7 @@ Namespaced elements Test constant - .. php:attr:: property + .. php:property:: property A property! @@ -240,7 +240,7 @@ Namespaced elements A normal instance method. -.. php:attr:: property +.. php:property:: property A property @@ -312,7 +312,7 @@ Within a namespace context you don't need to include the namespace in links. :php:function:`LibraryClass::instanceMethod` -:php:attr:`LibraryClass::$property` +:php:property:`LibraryClass::$property` :php:const:`LibraryClass::TEST_CONST` @@ -322,7 +322,7 @@ Within a namespace context you don't need to include the namespace in links. :php:function:`NamespaceClass::firstMethod` -:php:attr:`NamespaceClass::$property` +:php:property:`NamespaceClass::$property` :php:const:`NamespaceClass::NAMESPACE_CONST` @@ -365,7 +365,7 @@ All of the following links should not be prefixed with a classname. :php:const:`~LibraryClass::TEST_CONST` -:php:attr:`~LibraryClass::$property` +:php:property:`~LibraryClass::$property` Test Case - global access @@ -381,9 +381,9 @@ Test Case - global access :php:function:`in_array()` -:php:attr:`\\LibraryName\\LibraryClass::$property` +:php:property:`\\LibraryName\\LibraryClass::$property` -:php:attr:`~\\LibraryName\\LibraryClass::$property` Should not be prefixed with classname. +:php:property:`~\\LibraryName\\LibraryClass::$property` Should not be prefixed with classname. :php:const:`\\LibraryName\\LibraryClass::TEST_CONST`