www.digitalmars.com         C & C++   DMDScript  

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

reply d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=644

           Summary: Ddoc: aliases used as parameters/fields revert to base
                    type in generated docs.
           Product: D
           Version: 0.176
          Platform: PC
        OS/Version: Windows
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DMD
        AssignedTo: bugzilla digitalmars.com
        ReportedBy: tomas famolsen.dk


/// Alias for something
alias something A;

/// Some function
void func(A a);

---------------------
The above will generate docs like:

alias A;
void func(something a);


--
Dec 04 2006
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=644






In my case this is problematic because:

// code
version(Windows) alias HWND WindowPeer;
else version(Motif) alias Widget WindowPeer;
else version(GTK) alias GtkWidget* WindowPeer;

// docs
alias void* WindowPeer;

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

In the docs all occurences of WindowPeer is replaced with void* :/

A workaround is to do:
typedef void* WindowPeer_;
alias WindowPeer_ WindowPeer;

This is better but the name will never be correct.

If I just do
typedef void* WindowPeer;
I can't have the alias documented correctly as an alias!


--
Dec 06 2006
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=644






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.


--
Dec 12 2006
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=644


deewiant gmail.com changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |onlystupidspamhere yahoo.se





*** Bug 1271 has been marked as a duplicate of this bug. ***


--
Jun 18 2007
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=644


Andrei Alexandrescu <andrei metalanguage.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |ASSIGNED
                 CC|                            |andrei metalanguage.com
         AssignedTo|nobody puremagic.com        |bugzilla digitalmars.com


-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Nov 26 2010
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=644


Andrej Mitrovic <andrej.mitrovich gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|ASSIGNED                    |RESOLVED
                 CC|                            |andrej.mitrovich gmail.com
         Resolution|                            |WORKSFORME



11:48:10 PST ---
Works in 1.076 and 2.061. D2 will additionally export aliases (See Issue 5446).

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Jan 13 2013