On 8/16/07, Stanislav Malyshev <[EMAIL PROTECTED]> wrote: > > 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
I recently posted a note on the subject, see http://news.php.net/php.doc/969377231 <function /> will not create links to the current page. Example: <refentry xml:id="function.foobar" xmlns="http://docbook...";> <refnamediv>....</refnamediv> ... <refsect...> <para><function>foobar</function> is a awesome function!</para> </refsect... </refentry> Will generate: <b>foobar()</b> <function /> always adds (). > 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: <function> People were randomly using link and xref to link to methods, some used <function> but that didn't create any links for methods (in fact, if it did create a link at all it was to completely wrong file. HttpMessage:header() for instance was linked to ext/standard header().... :) > 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?) The filename is created from the xml:id, so if the ID is function.mysqli-autocommit then yes, both will create link to function.mysqli-autocommit. (Well, no. You'll have to remove the (). As I said above, <function> will add () automatically :) If the content of <function> has "::", "->" or "_" it will be replaced with "-". > What if OO and procedural have different names, like Format->getError > and format_get_error? Life sucks :) Depending on the xml:id you can only create a link the OO way or the procedural way. > > > 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. We know. Thats why everyone is postponing the SPL docs for instance. I was going to create OO skeleton this summer, but without an implementation it is totally useless to create skeletons that cannot be used. After PhD has caught up on all the current phpbook features I will post my suggestion of OO skel with PhD implementation for it. > > 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/ I don't have the time to check it out at the moment, hopefully someone else will :] -Hannes
