PHP Documentation - Re: [PHP-DOC] Re: New skeletons

Author

Re: [PHP-DOC] Re: New skeletons

Hannes Magnusson

2007-10-28, 7:05 pm

On 10/28/07, Edward Z. Yang <edwardzyang@thewritingpot.com> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hannes Magnusson wrote:
>
> Is there any way to abbreviate the XPointers?

Not really, no.

>
> Do we have any extensions already using this format yet? I'm not really
> sure I can comment until I see it in action, but the structure looks
> quite intuitive and good.

In the REF_STRUCT_DEV branch: mysqli, xmlreader, reflection, imagick
and http are using a variation (older draft) of these skeletons.

-Hannes

Philip Olson

2007-10-29, 10:07 pm

Hello Hannes and everyone,

Let's do this, let's welcome in the new era of PHP documentation book
style and classy OOP syntax. Great job Hannes! You again deserve the
much coveted phpdoc gold star :)

Regards,
Philip

Edward Z. Yang

2007-10-31, 7:03 pm

Hannes Magnusson wrote:
> Do we really want that?
> I suppose we can create a page for class overview and print all the
> classes on one page in the same way as the class reference does...

One of the great things about XSLT is that it makes things like this
specifically possible. I don't see why not.

> If we don't have the classname there we cannot link to the method
> since we don't know to which class it belongs to (may be inherited..).

I understand XSLT has somewhat deficient string comparison facilities,
but what if the class name was omitted if it was equal to the current
class definition?

--
Edward Z. Yang GnuPG: 0x869C48DA
HTML Purifier <http://htmlpurifier.org> Anti-XSS Filter
[[ 3FA8 E9A9 7385 B691 A6FC B3CB A933 BE7D 869C 48DA ]]

Edward Z. Yang

2007-10-31, 10:02 pm

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hannes Magnusson wrote:
> We are ditching xslt in favor of the new PHP based rendering system
> (see the top news entry on php.net :)), called PhD, which uses 3% of
> the time the xslt rendering takes...

My apologies, that was me talking before I'd have read
Buildsystem-proposal.rtf. Now, after having read that, and from my
limited readings of the source code (docs, docs, where are my docs? :-),
here's what my (probably incorrect) thoughts are:

Using XML Reader seems to be quite efficient, but though flexible (since
we can use PHP to arbitrarily process the internals), it lacks the
expressive pattern matching XSLT has. There is currently no well-defined
way for a PhDFormat::format_* function to do another traversal of a
different segment of the tree. In fact, because of XML Reader's design,
which allows for its low memory usage, this is impossible without
actually parsing a DOM and running XPath on it (or pregenerating it, as
we do with indices, as I understand it). Currently, we deal with this
issue by requiring any data to be used later to be early in the XML
file, so that the PhDFormat class can stash it away in its $tmp member
variable.

This is, however, irrelevant for the issue of duplicated class names.
Inspecting the source:

<refentry xml:id="function.xmlreader-close"
xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>XMLReader::close</refname>
<refpurpose>Close the XMLReader input</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>XMLReader::close</methodname>
<void/>
</methodsynopsis> [Snip]

Looking at <methodname>, it becomes clear that short of parsing the
string (relatively simple, but remember, this is XML) there is no way of
telling that XMLReader is the class name and close is the method name.
There are several ways to handle this:

1. Add the parsing code to PhD, so it can split up methodname into its
appropriate parts. :: serves as a sort of shorthand
2. Split up <methodname> into a <classname> and <methodname>. This
approach, not only embedding the information into the XML, also allows
us to swap out :: for a more appropriate -> if necessary (especially for
non-static functions)

However, determining when to omit classname and when to keep it would
have to be context dependant on the classname currently being used,
which would have to be stored in $tmp.

So, where am I totally off base?

- --
Edward Z. Yang GnuPG: 0x869C48DA
HTML Purifier <http://htmlpurifier.org> Anti-XSS Filter
[[ 3FA8 E9A9 7385 B691 A6FC B3CB A933 BE7D 869C 48DA ]]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHKRwcqTO+fYacSNoRAv1MAJ40fxdvbb2N
u28wL9kuhI6PmMLodQCeNBwE
QMKrogP9hef6PqFXI8o5o74=
=koY0
-----END PGP SIGNATURE-----

Sponsored Links