A couple of Ddoc changes

Chris Nicholson-Sauls ibisbasenji at gmail.com
Sun Apr 22 01:37:07 PDT 2007


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



More information about the Digitalmars-d mailing list