www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - Ddoc and version

reply Derek Parnell <derek nomail.afraid.org> writes:
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
Aug 17 2006
parent reply Walter Bright <newshound digitalmars.com> writes:
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()
   {
	...
   }
Aug 17 2006
next sibling parent reply Sean Kelly <sean f4.ca> writes:
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
Aug 17 2006
parent reply Derek Parnell <derek psyc.ward> writes:
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!"
Aug 17 2006
parent Derek Parnell <derek nomail.afraid.org> writes:
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
Aug 17 2006
prev sibling next sibling parent Derek Parnell <derek psyc.ward> writes:
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!"
Aug 17 2006
prev sibling parent Derek Parnell <derek psyc.ward> writes:
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!"
Aug 17 2006