Thread overview
Ddoc and version
Aug 17, 2006
Derek Parnell
Aug 17, 2006
Walter Bright
Aug 17, 2006
Sean Kelly
Aug 17, 2006
Derek Parnell
Aug 18, 2006
Derek Parnell
Aug 17, 2006
Derek Parnell
Aug 17, 2006
Derek Parnell
August 17, 2006
This may not be a bug in that this might be the way is was intended to behave, however if it a nuisance.

  version(XYZZY)
  {
   /** Some description.
   */
  }
  else
  {
   /** Some other description.
   */
  }
  void someFunc()
  {
     ...
  }

This results in no documentation for the function.

To get anything I have to do ...

  version(XYZZY)
  {
   /** Some description.
   */
   void someFunc()
   {
     ...
   }
  }
  else
  {
   /** Some other description.
   */
   void someFunc()
   {
     ...
   }
  }

Notice that I have to repeat the function's source code, which now doubles my maintenance effort for it. Not happy. :(

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
"Down with mediocrity!"
17/08/2006 5:53:58 PM
August 17, 2006
version is a problem with Ddoc, however, it may be a generally unresolvable one.

But I think it's a little odd that you'd have two different descriptions for the same code???

Here's a way to do it, not the nicest, but workable:

  version(XYZZY)
  {
   /** Some description.
   */
   void someFunc() { implementation(); }
  }
  else
  {
   /** Some other description.
   */
   void someFunc() { implementation(); }
  }

  void implementation()
  {
	...
  }
August 17, 2006
Walter Bright wrote:
> version is a problem with Ddoc, however, it may be a generally unresolvable one.
> 
> But I think it's a little odd that you'd have two different descriptions for the same code???
> 
> Here's a way to do it, not the nicest, but workable:
> 
>   version(XYZZY)
>   {
>    /** Some description.
>    */
>    void someFunc() { implementation(); }
>   }
>   else
>   {
>    /** Some other description.
>    */
>    void someFunc() { implementation(); }
>   }
> 
>   void implementation()
>   {
>     ...
>   }

You can also document a function declaration:

version(XYZZY)
{
  /** Some description.
   */
  void someFunc();
}
else
{
  /** Some other description.
   */
  void someFunc();
}

void someFunc()
{
  ...
}

In a few cases I generate docs inside version(DDoc) blocks rather than above the actual implementation, either because I have different versions of a function for different platforms and I don't want to tie the docs to a specific platform block, or because I'm using some dirty trick to declare the function that I don't want the user to be aware of.  This last case is most common in code where I'm hacking around ITI limitations and the function decl doesn't exactly match what it 'should' be.


Sean
August 17, 2006
On Thu, 17 Aug 2006 13:43:39 -0700, Walter Bright wrote:

> version is a problem with Ddoc, however, it may be a generally unresolvable one.

Nah ... your better than that!

> But I think it's a little odd that you'd have two different descriptions for the same code???

It was a cut-down example of the *type* of thing I was doing.

In reality I was trying to document the two editions of my booltype class, one with three values : True, False and Unknown, and another with only True and False. I use version() to enable generation of the two editions.

-- 
Derek Parnell
Melbourne, Australia
"Down with mediocrity!"
August 17, 2006
On Thu, 17 Aug 2006 14:29:39 -0700, Sean Kelly wrote:


> 
> You can also document a function declaration:
> 
> version(XYZZY)
> {
>    /** Some description.
>     */
>    void someFunc();
> }
> else
> {
>    /** Some other description.
>     */
>    void someFunc();
> }
> 
> void someFunc()
> {
>    ...
> }
> 
> In a few cases I generate docs inside version(DDoc) blocks rather than
> above the actual implementation, either because I have different
> versions of a function for different platforms and I don't want to tie
> the docs to a specific platform block, or because I'm using some dirty
> trick to declare the function that I don't want the user to be aware of.
>   This last case is most common in code where I'm hacking around ITI
> limitations and the function decl doesn't exactly match what it 'should' be.

Hmmm ... I'll give it try. Thanks.

-- 
Derek Parnell
Melbourne, Australia
"Down with mediocrity!"
August 17, 2006
On Thu, 17 Aug 2006 13:43:39 -0700, Walter Bright wrote:

> version is a problem with Ddoc, however, it may be a generally unresolvable one.

Hang on ... its not unresolvable. I just remembered I was doing it in the documentation system I wrote for Euphoria source code.

-- 
Derek Parnell
Melbourne, Australia
"Down with mediocrity!"
August 18, 2006
On Fri, 18 Aug 2006 08:01:43 +1000, Derek Parnell wrote:

> On Thu, 17 Aug 2006 14:29:39 -0700, Sean Kelly wrote:
> 
>> 
>> You can also document a function declaration:
>> 
>> version(XYZZY)
>> {
>>    /** Some description.
>>     */
>>    void someFunc();
>> }
>> else
>> {
>>    /** Some other description.
>>     */
>>    void someFunc();
>> }
>> 
>> void someFunc()
>> {
>>    ...
>> }
>> 
>> In a few cases I generate docs inside version(DDoc) blocks rather than
>> above the actual implementation, either because I have different
>> versions of a function for different platforms and I don't want to tie
>> the docs to a specific platform block, or because I'm using some dirty
>> trick to declare the function that I don't want the user to be aware of.
>>   This last case is most common in code where I'm hacking around ITI
>> limitations and the function decl doesn't exactly match what it 'should' be.
> 
> Hmmm ... I'll give it try. Thanks.

Thanks, that worked.

    version(DDOC)
    {
        version(BoolUnknown)
        {
        /**
           * Convert to a displayable string.
           *
           * False displays as "False" and True displays as "True".
           *
           * $(B Note:) However if the value has not been set yet, this
           * returns "Unknown".
           *
           * Examples:
           *  --------------------
           *   Bool a = SomeFunc();
           *   std.stdio.writefln("The result was %s", a);
           *  --------------------
        **/
            char[] toString();
        }
        else
        {
        /**
           * Convert to a displayable string.
           *
           * False displays as "False" and True displays as "True".
           *
           * Examples:
           *  --------------------
           *   Bool a = SomeFunc();
           *   std.stdio.writefln("The result was %s", a);
           *  --------------------
        **/
            char[] toString();
        }
    }
    else
    {

        char[] toString()
        {
            version(BoolUnknown)
            {
            if (m_Val == -1)
                return "Unknown".dup;
            }

            if (m_Val == 1)
                return "True".dup;

            return "False".dup;
        }
    }

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
"Down with mediocrity!"
18/08/2006 10:09:49 AM