1. Reflection methods don't have/need separate documentation.
2. Long pages are practical.

I can accept #1, but as for #2, I agree long pages can be more practical... However, without anchor tags being used, it makes that one long page very unfriendly.  It'd be great if you could add links at the top of the page that jump down to each class' section.

There /are/ anchor tags. See: http://php.net/reflection#language.oop5.reflection.reflectionexception
for example.

S

Granted, but there doesn't seem to be any reference to any of them on that page itself?

What envision being a LOT more user-friendly and intuitive is at the very top of that page, in the box that lists out all the classes, have the class name be a link to the anchor for that particular class.  I don't find it easy to scroll through the page and find a particular class.

I agree, but this won't change using the current build system.
I also think we should refactor those docs into the funcref where all other extensions are documented.

The main problem here is the fact our OO docs simply suck and I am looking into how we can make them better.

@bjori:

Are you saying the current build system can't handle the changes I suggested to the HTML?

I just went to quickly find something that behaves similarly to what I would expect:

http://ca.php.net/manual/en/language.functions.php

On this page, at the top it has a TOC, and the first link goes down to an anchor on the page.  Maybe it can't be put in the box with all the class names I mentioned, but can't there be a TOC at least?

> Are you saying the current build system can't
> handle the changes I suggested to the HTML?

That is exactly what I am saying.
This is a limitation in the DocBook-XSL stylesheets.

> I just went to quickly find something that
> behaves similarly to what I would expect:
> 
> http://ca.php.net/manual/en/language.functions.php

These two pages use totally different markup, not even remotely close.
And no. We cannot use this markup for reflection.

-Hannes

..but we could create our own home made TOC with something like:
<simplelist>
<member><xref linkend="reflection.introduction" /></member>
<member><xref linkend="reflection.reflectionexception" /></member>
<member><xref linkend="reflection.reflectionparameter" /></member>
...
</simplelist>

Feels really dirty but it will get the job done until we refactor these docs.

Philip: what do you think?

Sounds good, go for it.

This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.

Added homemade TOC on the top.
Regarding moving these docs to the 'Function Reference', that will happen when we have redesigned our index (see bug#39083).