Preserve the documentation

[aminya]

Dpp now preserves the documentation which means the editors will show data tips when the bound functions are used. :tada:

Fixed issues

Fixes #140

Description

Preserve the documentation on:

• [x] functions
• [x] variables
• [x] struct/class itself
• [x] struct/class properties
• [x] struct/class methods
• [x] enum itself
• [x] enum properties
• [x] aliases

Verification

All tests including the new ones pass:

Examples

Sample header file:

test.dpp

#include "./test.hpp"

test.hpp

/** f1 doc */
void f1() {}

// f2 non-doc
void f2() {}

/// f3 doc
void f3() {}

/** variable1 doc */
int variable1 = 1 + 2;

/// variable2 doc
int variable2 = 1 + 2;

// variable3 non-doc
int variable3 = 1 + 2;

/** Struct1 doc */
struct Struct1 {

  /** prop1 doc */
  int prop1;

  /** method1 doc */
  void method1();
};

/** Enum1 doc */
enum Enum1 {
  /** x doc */
  x,
  /// y doc
  y,
  // z non doc
  z,
};

/** Type1 doc */
typedef int Type1;

The output: test.d

extern(C++)
{
    /** Type1 doc */
    alias Type1 = int;
    /** Enum1 doc */
    enum Enum1
    {
        /** x doc */
        x = 0,
        /// y doc
        y = 1,
        /// y doc
        z = 2,
    }
    enum x = Enum1.x;
    enum y = Enum1.y;
    enum z = Enum1.z;
    /** Struct1 doc */
    struct Struct1
    {
        /** prop1 doc */
        int prop1;
        /** method1 doc */
        pragma(mangle, "?method1@Struct1@@QEAAXXZ") void method1() @nogc nothrow;
    }

    pragma(mangle, "?variable3@@3HA") extern __gshared int variable3;
    /// variable2 doc
    pragma(mangle, "?variable2@@3HA") extern __gshared int variable2;
    /** variable1 doc */
    pragma(mangle, "?variable1@@3HA") extern __gshared int variable1;
    /// f3 doc
    pragma(mangle, "?f3@@YAXXZ") void f3() @nogc nothrow;

    pragma(mangle, "?f2@@YAXXZ") void f2() @nogc nothrow;
    /** f1 doc */
    pragma(mangle, "?f1@@YAXXZ") void f1() @nogc nothrow;
}

Future benefits

This also paves the way for optionally using the annotations in the docs to make better bindings. For example, if a C function says that one of the parameters is @param[in], then we can also make that parameter in inside the D header. There are a bunch of these special Doxygen attributes that we can potentially use: https://www.doxygen.nl/manual/commands.html

[atilaneves]

Rebase?

[aminya]

You should release a new version of libclang and bump the version in dub.json.

[atilaneves]

You should release a new version of libclang and bump the version in dub.json.

Good points.

[atilaneves]

The last libclang changes (almost certainly the attempt to fix memory leaks) cause dpp's tests to crash.

[aminya]

The last libclang changes (almost certainly the attempt to fix memory leaks) cause dpp's tests to crash.

We should open an issue in libclang to find the reason for the crash. Allowing memory leaks to prevent a crash should be just a temporary work around 🤔

[atilaneves]

The last libclang changes (almost certainly the attempt to fix memory leaks) cause dpp's tests to crash.

We should open an issue in libclang to find the reason for the crash. Allowing memory leaks to prevent a crash should be just a temporary work around thinking

If you wish. It's not a high priority for me to fix it though.