Skip to content

8.3: Document Random\IntervalBoundary #3419

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.

Sign up for GitHub

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

Merged
merged 4 commits into from
Nov 20, 2024
+83 −0
Merged

8.3: Document Random\IntervalBoundary #3419

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a882a03
Proposal for Enum markup
Girgias May 27, 2024
0fcc62a
Add descriptions
Girgias Nov 17, 2024
48086f7
Update reference/random/random.intervalboundary.xml
Girgias Nov 20, 2024
9e1e997
Review + version.xml
Girgias Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions reference/random/book.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
&reference.random.reference;

&reference.random.random.randomizer;
&reference.random.random.intervalboundary;

&reference.random.random.engine;
&reference.random.random.cryptosafeengine;
Expand Down
75 changes: 75 additions & 0 deletions reference/random/random.intervalboundary.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
<?xml version="1.0" encoding="utf-8"?>
<reference xmlns="http://docbook.org/ns/docbook" xml:id="enum.random.intervalboundary" role="enum">
<title>Random\IntervalBoundary</title>
<titleabbrev>Random\IntervalBoundary</titleabbrev>

<partintro>
<section xml:id="enum.random.intervalboundary.intro">
&reftitle.intro;
<simpara>
The <enumname>Random\IntervalBoundary</enumname> cases determines if the
boundary values can be returned or not by
<methodname>Random\Randomizer::getFloat</methodname>.
</simpara>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if I would make it specific to Randomizer::getFloat(). It's the only current use case and it will likely remain the only use case, but technically the enum would be reusable for other things. The detail that it will determine whether the boundaries can be returned is already explained in the $boundary parameter of getFloat().

Perhaps something like:

The Random\IntervalBoundary enum specifies whether or not an interval includes the boundary values within the set of values lying in the interval.

</section>

<section xml:id="enum.random.intervalboundary.synopsis">
&reftitle.enumsynopsis;

<enumsynopsis>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a FYI: we should also think about the markup for implemented interfaces, enum constants, methods

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right... I forgot that PHP enums can do this sort of stuff...

Copy link
Member

@kocsismate kocsismate May 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, and I've just realized that e.g. fieldsynopsis elements inside enumsynopsis are not even allowed in DocBook. :/ (Or are they?)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, they are not, because DocBook (rightfully) assumes that enums are just that, and not our weird thing based on objects.

I think we might need to use the <classsynopsis> tags when an enum has constants, properties, or methods. However, I would imagine this to be rare for internal enums.

<enumname>Random\IntervalBoundary</enumname>

<enumitem>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other types of symbols have a dedicated section title for classes and interfaces. Would it be a good idea to add them for enums as well?

<enumidentifier>ClosedOpen</enumidentifier>
<enumitemdescription>
The <parameter>min</parameter> value may be returned.
However, the <parameter>max</parameter> value will never be returned.
</enumitemdescription>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A left-open interval. The lower boundary is included in the interval, the upper boundary is not.

</enumitem>

<enumitem>
<enumidentifier>ClosedClosed</enumidentifier>
<enumitemdescription>
Both the <parameter>min</parameter> and <parameter>max</parameter> value may be returned.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A closed interval. Both boundary values are included in the interval.

</enumitemdescription>
</enumitem>

<enumitem>
<enumidentifier>OpenClosed</enumidentifier>
<enumitemdescription>
The <parameter>max</parameter> value may be returned.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A right-open interval. The upper boundary is included in the interval, the lower boundary is not.

However, the <parameter>min</parameter> value will never be returned.
</enumitemdescription>
</enumitem>

<enumitem>
<enumidentifier>OpenOpen</enumidentifier>
<enumitemdescription>
Neither the <parameter>min</parameter> or <parameter>max</parameter> will ever be returned.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An open interval. Neither boundary value is included in the interval.

</enumitemdescription>
</enumitem>

</enumsynopsis>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, so far classsynopsis elements only contained the signature itself, but not the descriptions. Is it intentional that it's different for enumsynopsis elements?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The DocBook 5.2 markup describes the markup in that manner: https://tdg.docbook.org/tdg/5.2/enumsynopsis (via the <enumitem> tag) so yes.

For reference, the <classsynopsis> description is located here: https://tdg.docbook.org/tdg/5.2/classsynopsis

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a pity, because this way automatic replacement is going to be much more difficult, since there are free form values in the generated enumsynopsis item, and we should somehow try to preserve them.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a pity, because this way automatic replacement is going to be much more difficult, since there are free form values in the generated enumsynopsis item, and we should somehow try to preserve them.

I'm not sure whether that's difficult? One just needs to ignore the <enumitemdescription> tag, but also, I don't see how an enum would change after it has been introduced.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

classsynopsis elements are generated based on the current stub definitions for each class/interface/enum signature which are encountered on class synopses pages (https://github.com/php/php-src/blob/0ad2e4d997549c85aac61120a94ea3da0b709339/build/gen_stub.php#L5560) and then the respective elements are replaced altogether one by one (the replaceAndCompareXmls() call a few lines below).

This means that if there is anything inside classsynopsis elements which are not generatable based on the definitions in stubs, then those things will be removed. A workaround for enums could be that the enum case descriptions are retrieved from the manual pages and they are inserted into the generated elements... This complicates the process, but maybe it's not that difficult if this is going to be the preferred approach.

Also, It has just came to my mind that these descriptions would result in enum definitions which are completely not valid PHP code 🤔 while for the rest of the symbols, we generate at least a remotely valid PHP code since a few years.

</section>
</partintro>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->