Re: [docbook] What should the return type be for constructorsynopsisand destructorsynopsis.

[Stefan Seefeld <seefeld@sympatico.ca>]

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...