On 05/13/2010 04:48 AM, Richard Quadling wrote:
Hi.
I'm refining some documentation (PHP) which has used methodsynopsis
for the constructor and the destructor ...
<methodsynopsis>
<type>void</type>
<methodname>HttpRequestPool::__construct</methodname>
<methodparam choice="opt">
<type>HttpRequest</type>
<parameter>request</parameter>
</methodparam>
</methodsynopsis>
is now ...
<constructorsynopsis>
<void />
<methodname>HttpRequestPool::__construct</methodname>
<methodparam choice="opt">
<type>HttpRequest</type>
<parameter>request</parameter>
</methodparam>
</constructorsynopsis>
Is this "correct"?
For "void", the tdg says "An empty element in a function synopsis
indicating that the function in question takes no arguments", but
later says "The Void element produces generated text that indicates
the function has no arguments (or returns nothing). "
This suggests that "<void/>" may be used instead of "<methodparam>", as
the documentation explicitly mentions arguments, but not return values.
Also, the question appears to be very (programming-) language specific:
For example, in C++, constructors (and some other operations) do not
have return types. So putting "<void/>" there is (at least
syntactically) wrong. I don't know PHP and thus can't argue about that.
For function arguments, things are similar:
The fact that a function doesn't take any argument can already be
deduced from their absence from the declaration (at least in modern C,
in contrast to K&R C !), so I don't see a need for "<void/>" to indicate
an empty function parameter list, either, at least in modern C or C++. I
don't know about PHP.
HTH,
Stefan
--
...ich hab' noch einen Koffer in Berlin...
---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-h...@lists.oasis-open.org
