deprecate "staticmethod" in favor of static "method"

markstory · Aug 1, 2023 · a785d1a · a785d1a
1 parent 050153e
commit a785d1a
Show file tree

Hide file tree

Showing 5 changed files with 42 additions and 67 deletions.
diff --git a/doc/reference.rst b/doc/reference.rst
@@ -145,11 +145,6 @@ Each directive populates the index, and or the namespace index.
         
            This is an instance method.
 
-.. rst:directive:: .. php:staticmethod:: ClassName::methodName(signature)
-
-    Describe a static method, its arguments, return value and exceptions,
-    see :rst:dir:`php:method` for options.
-
 .. rst:directive:: .. php:property:: name
 
    Describe a property on a class.
@@ -193,11 +188,9 @@ matching directive is found:
 
 .. rst:role:: php:method
 
-   Reference a method of a class/interface/trait. This role supports
-   both kinds of methods::
+   Reference a method of a class/interface/trait::
    
      :php:method:`DateTime::setDate`
-     :php:method:`Classname::staticMethod`
 
 .. rst:role:: php:property
 

diff --git a/sphinxcontrib/phpdomain.py b/sphinxcontrib/phpdomain.py
@@ -673,7 +673,7 @@ class PhpDomain(Domain):
         'const': PhpNamespacelevel,
         'class': PhpClasslike,
         'method': PhpClassmember,
-        'staticmethod': PhpClassmember,
+        'staticmethod': PhpClassmember, # deprecated, use "method" with "static" visibility, methods in PHP are exclusively static or non-static
         'property': PhpClassmember,
         'attr': PhpClassmember, # deprecated, use "property"
         'case': PhpClassmember,

diff --git a/test/log.txt b/test/log.txt
@@ -1,6 +1,6 @@
 test/ns.md:48: [phpdomain.info] Target A2::simplify not found
 test/ns.md:53: [phpdomain.info] Target Bar2\A::simplify not found
-test/rst_doc.md:502: [phpdomain.info] Target OtherLibrary\ReturningClass\int|string|OtherLibrary\ReturnedClass|LibraryName\SubPackage\SubpackageInterface|null not found
+test/rst_doc.md:478: [phpdomain.info] Target OtherLibrary\ReturningClass\int|string|OtherLibrary\ReturnedClass|LibraryName\SubPackage\SubpackageInterface|null not found
 test/rst_doc2.md:11: [phpdomain.info] Target Imagine\Image\ImageInterface::draw not found
 test/rst_doc2.md:17: [phpdomain.info] Target Imagine\Image\PointInterface not found
 test/rst_doc2.md:17: [phpdomain.info] Target Imagine\Image\BoxInterface not found

diff --git a/test/rst_doc.html b/test/rst_doc.html
@@ -244,21 +244,25 @@ <h2>Classes<a class="headerlink" href="#classes" title="Permalink to this headin
           <p>This class constant wasn&#x2019;t indented</p>
         </dd>
       </dl>
-      <dl class="php staticmethod">
-        <dt class="sig sig-object php" id="OtherClass::staticMethod">
-          <em class="property">
-            <span class="pre">static</span>
-          </em>
+      <dl class="php method">
+        <dt class="sig sig-object php" id="OtherClass2::update">
           <span class="sig-prename descclassname">
-            <span class="pre">OtherClass::</span>
+            <span class="pre">OtherClass2::</span>
           </span>
           <span class="sig-name descname">
-            <span class="pre">staticMethod</span>
+            <span class="pre">update</span>
           </span>
-          <a class="headerlink" href="#OtherClass::staticMethod" title="Permalink to this definition">&#xB6;</a>
+          <span class="sig-paren">(</span>
+          <em class="sig-param">
+            <span class="pre">$arg</span>
+            <span class="pre">=</span>
+            <span class="pre">''</span>
+          </em>
+          <span class="sig-paren">)</span>
+          <a class="headerlink" href="#OtherClass2::update" title="Permalink to this definition">&#xB6;</a>
         </dt>
         <dd>
-          <p>A static method.</p>
+          <p>A method without explicitly declared class block.</p>
         </dd>
       </dl>
     </section>
@@ -508,9 +512,9 @@ <h3>Test Case - Global symbols with no namespaces<a class="headerlink" href="#te
           </a>
         </p>
         <p>
-          <a class="reference internal" href="#OtherClass::staticMethod" title="OtherClass::staticMethod">
+          <a class="reference internal" href="#OtherClass2::update" title="OtherClass2::update">
             <code class="xref php php-function docutils literal notranslate">
-              <span class="pre">OtherClass::staticMethod</span>
+              <span class="pre">OtherClass2::update</span>
             </code>
           </a>
         </p>
@@ -710,23 +714,6 @@ <h2>Namespaced elements<a class="headerlink" href="#namespace-LibraryName" title
           </dl>
         </dd>
       </dl>
-      <dl class="php staticmethod">
-        <dt class="sig sig-object php" id="LibraryName\LibraryClass::staticMethod">
-          <em class="property">
-            <span class="pre">static</span>
-          </em>
-          <span class="sig-prename descclassname">
-            <span class="pre">LibraryName\LibraryClass::</span>
-          </span>
-          <span class="sig-name descname">
-            <span class="pre">staticMethod</span>
-          </span>
-          <a class="headerlink" href="#LibraryName\LibraryClass::staticMethod" title="Permalink to this definition">&#xB6;</a>
-        </dt>
-        <dd>
-          <p>A static method in a namespace</p>
-        </dd>
-      </dl>
       <dl class="php class">
         <dt class="sig sig-object php" id="LibraryName\NamespaceClass">
           <em class="property">
@@ -784,26 +771,23 @@ <h2>Namespaced elements<a class="headerlink" href="#namespace-LibraryName" title
           <p>Const on class in namespace</p>
         </dd>
       </dl>
-      <dl class="php staticmethod">
-        <dt class="sig sig-object php" id="LibraryName\NamespaceClass::namespaceStatic">
-          <em class="property">
-            <span class="pre">static</span>
-          </em>
+      <dl class="php method">
+        <dt class="sig sig-object php" id="LibraryName\NamespaceClass2::update">
           <span class="sig-prename descclassname">
-            <span class="pre">LibraryName\NamespaceClass::</span>
+            <span class="pre">LibraryName\NamespaceClass2::</span>
           </span>
           <span class="sig-name descname">
-            <span class="pre">namespaceStatic</span>
+            <span class="pre">update</span>
           </span>
           <span class="sig-paren">(</span>
           <em class="sig-param">
             <span class="pre">$foo</span>
           </em>
           <span class="sig-paren">)</span>
-          <a class="headerlink" href="#LibraryName\NamespaceClass::namespaceStatic" title="Permalink to this definition">&#xB6;</a>
+          <a class="headerlink" href="#LibraryName\NamespaceClass2::update" title="Permalink to this definition">&#xB6;</a>
         </dt>
         <dd>
-          <p>A static method here.</p>
+          <p>A method without explicitly declared class block in a namespace</p>
         </dd>
       </dl>
       <dl class="php class">
@@ -978,13 +962,6 @@ <h3>Test Case - not including namespace<a class="headerlink" href="#test-case-no
             </code>
           </a>
         </p>
-        <p>
-          <a class="reference internal" href="#LibraryName\LibraryClass::staticMethod" title="LibraryName\LibraryClass::staticMethod">
-            <code class="xref php php-function docutils literal notranslate">
-              <span class="pre">LibraryClass::staticMethod()</span>
-            </code>
-          </a>
-        </p>
         <p>
           <a class="reference internal" href="#LibraryName\LibraryClass::$property" title="LibraryName\LibraryClass::$property">
             <code class="xref php php-property docutils literal notranslate">
@@ -1034,6 +1011,13 @@ <h3>Test Case - not including namespace<a class="headerlink" href="#test-case-no
             </code>
           </a>
         </p>
+        <p>
+          <a class="reference internal" href="#LibraryName\NamespaceClass2::update" title="LibraryName\NamespaceClass2::update">
+            <code class="xref php php-method docutils literal notranslate">
+              <span class="pre">NamespaceClass2::update()</span>
+            </code>
+          </a>
+        </p>
         <p>
           <a class="reference internal" href="#LibraryName\LibraryClassFinal" title="LibraryName\LibraryClassFinal">
             <code class="xref php php-class docutils literal notranslate">
@@ -1846,14 +1830,16 @@ <h3>Advanced Enumerations<a class="headerlink" href="#namespace-Example\Advanced
                 <p>Returns &#x201C;red&#x201D; for hearts and diamonds, &#x201C;black&#x201D; for clubs and spades.</p>
               </dd>
             </dl>
-            <dl class="php staticmethod">
+            <dl class="php method">
               <dt class="sig sig-object php" id="Example\Advanced\Suit::values">
                 <em class="property">
                   <span class="pre">static</span>
                 </em>
                 <span class="sig-name descname">
                   <span class="pre">values</span>
                 </span>
+                <span class="sig-paren">(</span>
+                <span class="sig-paren">)</span>
                 <span class="sig-return">
                   <span class="sig-return-icon">&#x2192;</span>
                   <span class="sig-return-typehint">

diff --git a/test/rst_doc.md b/test/rst_doc.md
@@ -79,9 +79,9 @@ Classes
 
     This class constant wasn't indented
 
-.. php:staticmethod:: OtherClass::staticMethod()
+.. php:method:: OtherClass2::update($arg = '')
 
-    A static method.
+    A method without explicitly declared class block.
 
 Interfaces
 ==========
@@ -172,7 +172,7 @@ Test Case - Global symbols with no namespaces
 
 :php:const:`OtherClass::NO_INDENT`
 
-:php:function:`OtherClass::staticMethod`
+:php:function:`OtherClass2::update`
 
 :php:interface:`DateTimeInterface`
 
@@ -238,10 +238,6 @@ Namespaced elements
 
         A property!
 
-.. php:staticmethod:: LibraryClass::staticMethod()
-
-    A static method in a namespace
-
 .. php:class:: NamespaceClass
 
     A class in the namespace, no indenting on children
@@ -258,9 +254,9 @@ Namespaced elements
 
     Const on class in namespace
 
-.. php:staticmethod:: namespaceStatic($foo)
+.. php:method:: NamespaceClass2::update($foo)
 
-    A static method here.
+    A method without explicitly declared class block in a namespace
 
 .. php:class:: final LibraryClassFinal
 
@@ -322,8 +318,6 @@ Within a namespace context you don't need to include the namespace in links.
 
 :php:function:`LibraryClass::instanceMethod`
 
-:php:function:`LibraryClass::staticMethod()`
-
 :php:property:`LibraryClass::$property`
 
 :php:const:`LibraryClass::TEST_CONST`
@@ -338,6 +332,8 @@ Within a namespace context you don't need to include the namespace in links.
 
 :php:const:`NamespaceClass::NAMESPACE_CONST`
 
+:php:method:`NamespaceClass2::update()`
+
 :php:class:`LibraryClassFinal`
 
 :php:method:`LibraryClassFinal::firstMethod`
@@ -537,7 +533,7 @@ Advanced Enumerations
 
         Returns "red" for hearts and diamonds, "black" for clubs and spades.
 
-    .. php:staticmethod:: values() -> string[]
+    .. php:method:: static values() -> string[]
 
         Returns an array of the values of all the cases on this enum.