If you wrap it inside a <function /> element then drop the (),
otherwise I'd say keep them
When does function tag create link and when it doesn't? I saw sometimes it does, but I'm pretty sure I saw cases when it doesn't. Generally, if I want to link to a function, should I use <function>, <link> or <xref>? I see most docs use this syntax in reference.xml:
<listitem>
<para><link linkend='function.mysqli-connect'>mysqli</link> - construct a new mysqli object</para>
</listitem>
Could I replace <link> with <function> there?
What if I have dual-api function (like mysqli, which has both OO and procedural syntax) but single manual entry describing both and I define two refnames - like mysqli:
<refnamediv>
<refname>mysqli_autocommit</refname>
<refname>mysqli->autocommit()</refname>
<refpurpose>Turns on or off auto-commiting database modifications</refpurpose>
</refnamediv>
Would both create right links with <function> tags (i.e. <function>mysqli_autocommit</function> and <function>mysqli->autocommit()</function> would link to the page named function.mysqli-autocommit.php?)
What if OO and procedural have different names, like Format->getError and format_get_error?
We don't have a "official" OO doc-style, what comes closest is the
pecl/http docs.
Maybe it's good time to make some? Not that I'm volunteering but right now in the manual OO extension doc styles are so different it's outright confusing.
You could send a file, or two, to the list and have people check it
out for you...
Thanks, the docs I'm talking about are in
http://cvs.php.net/viewvc.cgi/pecl/intl/doc/intl/
They are rather half-baked but they have enough "meat" to figure out general structure and I want to have a structure before we add more content.
But I'd also like to have a set of rules, since there's other people working on the same docs and in general it's better to understand what's going on and not just copy-paste things.
--
Stanislav Malyshev, Zend Software Architect
stas@zend.com http://www.zend.com/
(408)253-8829 MSN: stas@zend.com