-
Notifications
You must be signed in to change notification settings - Fork 8k
Fixes and improvements for class synopsis generation #10098
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
| $includeElement = $this->createIncludeElement( | ||
| $doc, | ||
| "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])" | ||
| ); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this create a fallback element that doesn't warn if it doesn't exist?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, it does:
Lines 2962 to 2974 in 002d54d
| private function createIncludeElement(DOMDocument $doc, string $query): DOMElement | |
| { | |
| $includeElement = $doc->createElement("xi:include"); | |
| $attr = $doc->createAttribute("xpointer"); | |
| $attr->value = $query; | |
| $includeElement->appendChild($attr); | |
| $fallbackElement = $doc->createElement("xi:fallback"); | |
| $includeElement->appendChild(new DOMText("\n ")); | |
| $includeElement->appendChild($fallbackElement); | |
| $includeElement->appendChild(new DOMText("\n ")); | |
| return $includeElement; | |
| } |
Girgias
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Other than the comment question LGTM
cmb69
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you!
| $includeElement = $this->createIncludeElement( | ||
| $doc, | ||
| "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])" | ||
| ); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, it does:
Lines 2962 to 2974 in 002d54d
| private function createIncludeElement(DOMDocument $doc, string $query): DOMElement | |
| { | |
| $includeElement = $doc->createElement("xi:include"); | |
| $attr = $doc->createAttribute("xpointer"); | |
| $attr->value = $query; | |
| $includeElement->appendChild($attr); | |
| $fallbackElement = $doc->createElement("xi:fallback"); | |
| $includeElement->appendChild(new DOMText("\n ")); | |
| $includeElement->appendChild($fallbackElement); | |
| $includeElement->appendChild(new DOMText("\n ")); | |
| return $includeElement; | |
| } |
|
Just before merging, I realized that the recent role attribute related changes have not been available in PHP 8.2, so I included the backport into this PR. |
Until php#10098 default constructors were sometimes documented, sometimes omitted. The above PR made adding documentation for constructor of all non-abstract classes required. However, this is not desired when such a class inherits a constructor from its parent. The current PR fixes the behavior the following way: - documents inherited constructors (along with destructors) - makes it possible to generate/replace the methodsynopsis of implicit default constructors which doesn't have a stub
Until php#10098 default constructors were sometimes documented, sometimes omitted. The above PR made adding documentation for constructor of all non-abstract classes required. However, this is not desired when such a class inherits a constructor from its parent. The current PR fixes the behavior the following way: - documents inherited constructors (along with destructors) - makes it possible to generate/replace the methodsynopsis of implicit default constructors which don't have a stub counterpart
Until php#10098 default constructors were sometimes documented, sometimes omitted. The above PR made adding documentation for constructor of all non-abstract classes required. However, this is not desired when such a class inherits a constructor from its parent. The current PR fixes the behavior the following way: - documents inherited constructors (along with destructors) - makes it possible to generate/replace the methodsynopsis of implicit default constructors which don't have a stub counterpart
Until #10098 default constructors were sometimes documented, sometimes omitted. The above PR made adding documentation for constructor of all non-abstract classes required. However, this is not desired when such a class inherits a constructor from its parent. The current PR fixes the behavior the following way: - documents inherited constructors (along with destructors) - makes it possible to generate/replace the methodsynopsis of implicit default constructors which don't have a stub counterpart
reference/spl/outofrangeexception.xml), so another replacement rule is added to the listAllowDynamicProperties::__construct()is not currently documented, but it has a stub. Conversely,SplStack::__construct()is documented, but it doesn't have a stub). Therefore, the only sensible way to have deterministic rules is to always document default constructors.