• Jordan Miner (19/19) Apr 21 2007 Here are a couple of changes that I would like to see in Ddoc.
• Chris Nicholson-Sauls (6/29) Apr 22 2007 In full agreement. Further, I'd like to see aliases DDoc'd a little bet...

Jordan Miner <jminer2613 nospam.students.pcci.edu> writes:

Here are a couple of changes that I would like to see in Ddoc.

The main problem in Ddoc that I cannot work around is that it does not generate
documentation for template mixins:
	///
	class Button {
		/// Occurs when the button is pushed with the mouse or keyboard.
		mixin Event!(whenClicked) clicked;
		///
		void whenClicked(EventArgs e) {}
	}
What if the user of the library needs to use some methods that were mixed in?
He cannot know from looking at the documentation that the mixed-in methods even
exist.

The other change is not as important. Currently if this is in a source file:
	alias char[] string;
	///
	string readText();
The documentation shows the return type as char[]. I am not sure if this is the
best way or not.
On one hand, I remember when I only knew Java and tried to learn C using the
Windows API. I gave up because I could figure out what type anything was.
DWORD, LPCTSTR, LPDWORD, WPARAM, LPARAM, LRESULT, LPTSTR, etc. Even the
standard library used size_t, time_t, etc. and I did not know what they were.
The current behavior makes the types clear.
On the other hand, as D does not really have this problem, I think that there
should be a switch to tell Ddoc to leave types the way they are written in the
source file.
If I have word and uword aliases that are defined to be 32 or 64 bits based on
the platform, the user would not be able to see where they are used by looking
at the documentation, instead seeing just int/long or uint/ulong depending on
what system the docs were generated on.

Jordan

Chris Nicholson-Sauls <ibisbasenji gmail.com> writes:

Jordan Miner wrote:
 Here are a couple of changes that I would like to see in Ddoc.
 
 The main problem in Ddoc that I cannot work around is that it does not
generate documentation for template mixins:
 	///
 	class Button {
 		/// Occurs when the button is pushed with the mouse or keyboard.
 		mixin Event!(whenClicked) clicked;
 		///
 		void whenClicked(EventArgs e) {}
 	}
 What if the user of the library needs to use some methods that were mixed in?
He cannot know from looking at the documentation that the mixed-in methods even
exist.
 
 The other change is not as important. Currently if this is in a source file:
 	alias char[] string;
 	///
 	string readText();
 The documentation shows the return type as char[]. I am not sure if this is
the best way or not.
 On one hand, I remember when I only knew Java and tried to learn C using the
Windows API. I gave up because I could figure out what type anything was.
DWORD, LPCTSTR, LPDWORD, WPARAM, LPARAM, LRESULT, LPTSTR, etc. Even the
standard library used size_t, time_t, etc. and I did not know what they were.
The current behavior makes the types clear.
 On the other hand, as D does not really have this problem, I think that there
should be a switch to tell Ddoc to leave types the way they are written in the
source file.
 If I have word and uword aliases that are defined to be 32 or 64 bits based on
the platform, the user would not be able to see where they are used by looking
at the documentation, instead seeing just int/long or uint/ulong depending on
what system the docs were generated on.
 
 Jordan
 

In full agreement.  Further, I'd like to see aliases DDoc'd a little better. 
Given 'alias 
char[] string;' it currently just documents 'alias string;'.  I'd rather it
show what 
/actual/ type 'string' is as well.  This would be almost a requirement in a
DDoc 
environment that provides what you (and I) are wanting here.

-- Chris Nicholson-Sauls