On Tue, 23 Mar 2010 06:41:36 -0400, TimK <[email protected]> wrote:

Hi!

I have a little (private) project in C++ and was thinking that I should give D
a chance (especially since it's not exactly new).

So I have a class TPerson where the declaration is in the header file and the
definition in the cpp-source file. Naturally a defined function looks
something like this:

void TCharacter::DoSomething(int x){...}

I do this for several reasons:
- The class would get really awkward to read through and understand, with all the code in it - so I usually just put the declaration and the documentation
for public functions into it.
- a programmer who just wants to understand the class doesn't care about the
implementation.

Now I tried to make a class in D, too, following this style.
Unfortunately that doesn't work and I couldn't find a working alternative in
the documentation.

Is this not possible in D?
(I'm using GDC, so I guess it's still D 1.0)

First, welcome!

Second, GDC is horrifically old. I'd recommend switching to ldc or the latest dmd 1.

Third, yes, it is somewhat possible. But you have to think about it a different way. When defining a class' implementation, you define everything inside the class. This means that instead of this:

void TCharacter::DoSomething(int x){...}
int TCharacter::SomeOtherFunction() {...}

you do this:

class TCharacter
{
   void DoSomething(int x){...}
   int SomeOtherFunction(){...}
}

It actually turns out to be less code to write because you don't have to repeat the class name over and over, and it reads better IMO to someone trying to understand the implementation.

If you want to provide a "header file" for this, you may do so with a di file (d interface). This file can have simply prototypes and documentation. It will look exactly like your class definition, but does not need to contain your implementations. In my example, the di file looks like this:

class TCharacter
{
   /**
    * Docs for DoSomething
    */
   void DoSomething(int x);

   /**
    * Docs for SomeOtherFunction()
    */
   int SomeOtherFunction();
}

The drawbacks of doing it this way are 1) you have to maintain two files instead of one, with almost identical contents and 2) di files without function implementations are not inlinable.

Note also, template functions must be included in the interface file, because the source must always be available to the compiler.

After explaining all that, and with my past experience with C++, I'd recommend *NOT* to do this. The D compiler has a builtin documentation generator, so someone trying to use your functions will want to turn to that instead (much easier to read), and maintenance on two files that have to always be in sync is sucky to say the least. The D compiler can auto-generate header files, but it is for the compiler's benefit, not a person's. All docs are stripped out, and indentations are removed. In addition, it tries to include implementations for functions which it thinks might be inlined.

For an example of what really good generated docs look like, see tango's docs: http://www.dsource.org/projects/tango/docs/current

My recommendation is to simply build your code inline, just like Java and C#, and use the doc generation tools to document your functions. It will take some getting used to, but I think you will appreciate the single-point-of-editing aspect of it.

Good luck!

-Steve

Reply via email to