[Issue 644] Ddoc: aliases used as parameters/fields revert to base type in generated docs.

[d-bugmail at puremagic.com]

http://d.puremagic.com/issues/show_bug.cgi?id=644





------- Comment #2 from tomas at famolsen.dk  2006-12-12 15:16 -------
I definitely think we need some more control over how aliases are documented.
Consider this code:

  import std.string;
  ///
  alias char[] Foo;
  ///
  alias int Bar;
  ///
  Foo func(Bar b)
  {
      return toString(b);
  }

This will be documented as:

  alias Foo;
  alias Bar;
  char[] func(int);

Here if the proposed bug is fixed would become:

  alias Foo;
  alias Bar;
  Foo func(Bar);

In the first example the docs show two aliases but it's impossible to see where
they are used.
In the second example the docs show two aliases and a function that uses them,
but it doesn't given any kind of clue as to what Foo and Bar might be.

I propose something like this...

--------------------------------------------

  /// some alias
  alias char[] Foo;
  /// some function
  Foo func(Foo);

becomes:

  alias Foo;
    some alias
  char[] func(char[]);
    some func

--------------------------------------------

  /// some alias
  /// KeepAlias:
  alias char[] Foo;
  /// some func
  Foo func(Foo);

becomes:

  alias char[] Foo;
    some alias
  Foo func(Foo);
    some func

--------------------------------------------

  /// some alias
  /// RefsKeepAlias:
  alias char[] Foo;
  /// some func
  Foo func(Foo);

becomes:

  alias Foo;
    some alias
  Foo func(Foo);
    some func

--------------------------------------------

The last one is needed when the alias is dependent on conditional compilation.
In those cases I think it's better to put the different things the alias can be
in the alias's description.


--