www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Document generator

reply Ant <duitoolkit yahoo.ca> writes:
This is more a curiosity then anything else
but I started a document generator from the
embeded comments on the source code
(as doxygen or javadoc).

For now it's intergrated with leds but it can be easelly
decoupled.

see an example at:

http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html



Ant
Dec 04 2004
next sibling parent reply Bastiaan Veelo <Bastiaan.N.Veelo ntnu.no> writes:
At last, a D doc generator! Thanks Ant, looks like you are on the right 
track. Are "mixin"s in yet?

Bastiaan.

Ant wrote:

 This is more a curiosity then anything else
 but I started a document generator from the
 embeded comments on the source code
 (as doxygen or javadoc).
 
 For now it's intergrated with leds but it can be easelly
 decoupled.
 
 see an example at:
 
 http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html
 
 
 
 Ant
Dec 05 2004
parent reply Ant <duitoolkit yahoo.ca> writes:
On Sun, 05 Dec 2004 12:19:41 +0100, Bastiaan Veelo wrote:


 At last, a D doc generator! Thanks Ant, looks like you are on the right 
 track. Are "mixin"s in yet?


no, not yet.
How should they be enumerated? just like the interfaces?
and then a link for each function/method?


 see an example at:
 
 http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html




The tags formating is drawfted - so the detailed comments looks better now.

Ant

PS
sourceforge CVS is ridiculous (hours to update) but dsource svn is usable.
I believe I'll be updating svn at dsource after every development session.
Dec 05 2004
parent reply Bastiaan Veelo <Bastiaan.N.Veelo ntnu.no> writes:
Ant wrote:

 On Sun, 05 Dec 2004 12:19:41 +0100, Bastiaan Veelo wrote:
 
 

At last, a D doc generator! Thanks Ant, looks like you are on the right 
track. Are "mixin"s in yet?


 
 
 no, not yet.
 How should they be enumerated? just like the interfaces?
 and then a link for each function/method?


Not sure what you mean. Do you have a link to an example with interfaces?

The thing is that besides generating documentation for the template 
itself, I think that classes that mix them in should have documentation 
with the mixins expanded, taking into account aliases. There is an 
earlier post with an example of what I mean.

http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/11298

The point is that using mixins as a way of cutting down on the 
Copy&Pasting is an implementation detail, and should be hidden from the 
user, or at least be transparent.


see an example at:

http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html




 
 
 The tags formating is drawfted - so the detailed comments looks better now.


I am not concerned about looks yet. Getting the basics right is the real 
work :-)

Bastiaan.
Dec 07 2004
next sibling parent reply "Regan Heath" <regan netwin.co.nz> writes:
On Tue, 07 Dec 2004 21:28:10 +0100, Bastiaan Veelo  
<Bastiaan.N.Veelo ntnu.no> wrote:

 Ant wrote:

 On Sun, 05 Dec 2004 12:19:41 +0100, Bastiaan Veelo wrote:


 At last, a D doc generator! Thanks Ant, looks like you are on the  
 right track. Are "mixin"s in yet?


   no, not yet.
 How should they be enumerated? just like the interfaces?
 and then a link for each function/method?


 Not sure what you mean. Do you have a link to an example with interfaces?

 The thing is that besides generating documentation for the template  
 itself, I think that classes that mix them in should have documentation  
 with the mixins expanded, taking into account aliases. There is an  
 earlier post with an example of what I mean.

 http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/11298

 The point is that using mixins as a way of cutting down on the  
 Copy&Pasting is an implementation detail, and should be hidden from the  
 user, or at least be transparent.


However, if you're reading documentation you don't really want to have to  
re-read the same thing 15 times to determine that it is indeed the same  
thing repeated 15 times.

Wouldn't it be better to link each mixin to one set of documentation so  
that once you've read it once you can immediately understand the use of it  
in each instance.

I guess before we can decide we'd need to see some concrete examples.

Regan
Dec 07 2004
parent reply Bastiaan Veelo <Bastiaan.N.Veelo ntnu.no> writes:
Regan Heath wrote:

 On Tue, 07 Dec 2004 21:28:10 +0100, Bastiaan Veelo  
 <Bastiaan.N.Veelo ntnu.no> wrote:
 

 http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/11298

 The point is that using mixins as a way of cutting down on the  
 Copy&Pasting is an implementation detail, and should be hidden from 
 the  user, or at least be transparent.


 
 
 However, if you're reading documentation you don't really want to have 
 to  re-read the same thing 15 times to determine that it is indeed the 
 same  thing repeated 15 times.


Good point.


 Wouldn't it be better to link each mixin to one set of documentation so  
 that once you've read it once you can immediately understand the use of 
 it  in each instance.


But then you would have to substitute every aliased identifier in your 
head, making the docs difficult to read.


 I guess before we can decide we'd need to see some concrete examples.


I should make some time and brush up the code of dcouple on dsource, 
that should provide an example which I am concerned about.

Regards,
Bastiaan.
Dec 07 2004
parent "Regan Heath" <regan netwin.co.nz> writes:
On Tue, 07 Dec 2004 22:52:15 +0100, Bastiaan Veelo  
<Bastiaan.N.Veelo ntnu.no> wrote:

 Regan Heath wrote:

 On Tue, 07 Dec 2004 21:28:10 +0100, Bastiaan Veelo   
 <Bastiaan.N.Veelo ntnu.no> wrote:


 http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/11298

 The point is that using mixins as a way of cutting down on the   
 Copy&Pasting is an implementation detail, and should be hidden from  
 the  user, or at least be transparent.


   However, if you're reading documentation you don't really want to  
 have to  re-read the same thing 15 times to determine that it is indeed  
 the same  thing repeated 15 times.


 Good point.


 Wouldn't it be better to link each mixin to one set of documentation  
 so  that once you've read it once you can immediately understand the  
 use of it  in each instance.


 But then you would have to substitute every aliased identifier in your  
 head, making the docs difficult to read.


True, aliases would complicate things.

If the docs were dynamic you could pass something in the link to the mixin  
doc causing it to display the aliases as you desire. Not sure if this is  
possible with static html pages. Maybe javascript or ASP or something  
could help?

Perhaps simply labelling the mixed in code with the mixin name will  
suffice.


 I guess before we can decide we'd need to see some concrete examples.


 I should make some time and brush up the code of dcouple on dsource,  
 that should provide an example which I am concerned about.


Good plan.

Regan
Dec 07 2004
prev sibling parent reply Ant <Ant_member pathlink.com> writes:
In article <cp53st$2agu$1 digitaldaemon.com>, Bastiaan Veelo says...

Ant wrote:

 On Sun, 05 Dec 2004 12:19:41 +0100, Bastiaan Veelo wrote:
 
 

At last, a D doc generator! Thanks Ant, looks like you are on the right 
track. Are "mixin"s in yet?


 
 
 no, not yet.
 How should they be enumerated? just like the interfaces?
 and then a link for each function/method?


Not sure what you mean. Do you have a link to an example with interfaces?


here http://dool.sourceforge.net/dool_sql_dpq_DPQConnect_DPQConnect.html

so, create another horizontal line and put "mixins mixed in:"
and further down a table with the links to the mixin function.


The thing is that besides generating documentation for the template 
itself, I think that classes that mix them in should have documentation 
with the mixins expanded, taking into account aliases. There is an 
earlier post with an example of what I mean.

http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/11298


I see, I'm thinking it should be marked the function came from somewhere
else, like the javadoc makes a distintion on the methods inherited
from the super classes.

like:
---------------------------------------------
Class "Italy"

Documentation for Italy class.

Public Members:

Public member from mixin "Implementation":

void func( Pasta t ): Do something interesting with Pasta.
---------------------------------------------


The point is that using mixins as a way of cutting down on the 
Copy&Pasting is an implementation detail, and should be hidden from the 
user, or at least be transparent.


the point is that now it's clear that any changes to "Implementation"
will be propagated to class Italy.


I am not concerned about looks yet. Getting the basics right is the real 
work :-)


not a joke (lessons in life - use carefully):
If you want to have success on our shallow society you have to change.
looks is every thing.
I already spent hours on my pages look an plan to improve them
more and more.
someone said "If you can't make it good, at least make it look good".

Ant
Dec 07 2004
parent Bastiaan Veelo <Bastiaan.N.Veelo ntnu.no> writes:
Ant wrote:

 In article <cp53st$2agu$1 digitaldaemon.com>, Bastiaan Veelo says...
 

Ant wrote:


On Sun, 05 Dec 2004 12:19:41 +0100, Bastiaan Veelo wrote:




At last, a D doc generator! Thanks Ant, looks like you are on the right 
track. Are "mixin"s in yet?



no, not yet.
How should they be enumerated? just like the interfaces?
and then a link for each function/method?


Not sure what you mean. Do you have a link to an example with interfaces?


 
 
 here http://dool.sourceforge.net/dool_sql_dpq_DPQConnect_DPQConnect.html
 
 so, create another horizontal line and put "mixins mixed in:"
 and further down a table with the links to the mixin function.


Yes, if the mixed in functions take the aliases into account, like you 
show below.


 I see, I'm thinking it should be marked the function came from somewhere
 else, like the javadoc makes a distintion on the methods inherited
 from the super classes.
 
 like:
 ---------------------------------------------
 Class "Italy"
 
 Documentation for Italy class.
 
 Public Members:
 
 Public member from mixin "Implementation":
 
 void func( Pasta t ): Do something interesting with Pasta.
 ---------------------------------------------
 


I like this. This is what I mean with "transparent".


The point is that using mixins as a way of cutting down on the 
Copy&Pasting is an implementation detail, and should be hidden from the 
user, or at least be transparent.


 
 
 the point is that now it's clear that any changes to "Implementation"
 will be propagated to class Italy.


Excellent. I'd say go for it, Ant! I am looking forward to this.


I am not concerned about looks yet. Getting the basics right is the real 
work :-)


 
 
 not a joke (lessons in life - use carefully):
 If you want to have success on our shallow society you have to change.
 looks is every thing.
 I already spent hours on my pages look an plan to improve them
 more and more.
 someone said "If you can't make it good, at least make it look good".


I think it is good that you are concerned about looks. I just meant to 
say that if you get the basics right, I think you can manage the lay-out 
too. And if you can not, lots of other people can. It is not a problem :-)


Regards,
Bastiaan.
Dec 07 2004
prev sibling next sibling parent reply Jan Bendtsen <dimon controlREMOVEME.aau.dk> writes:
Ant wrote:

 This is more a curiosity then anything else
 but I started a document generator from the
 embeded comments on the source code
 (as doxygen or javadoc).
 
 For now it's intergrated with leds but it can be easelly
 decoupled.
 
 see an example at:
 
 http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html


This is great! Please keep up the good work, Ant. If this continues, 
your projects will end up overtaking phobos in terms of pure 
functionality and all-over object-oriented goodness :-)

BTW, what was the result of that String discussion a week or so back? 
Should we all stick to char[], or can we use a real String class in the 
future? Inquiring minds want to know (... attempting to incorporate dool 
into another package/project).

Cheers,
Dimon
Dec 05 2004
next sibling parent reply Ant <duitoolkit yahoo.ca> writes:
On Sun, 05 Dec 2004 20:44:45 -0500, Jan Bendtsen wrote:


 Ant wrote:

 This is more a curiosity then anything else
 but I started a document generator from the
 embeded comments on the source code
 (as doxygen or javadoc).
 
 For now it's intergrated with leds but it can be easelly
 decoupled.
 
 see an example at:
 
 http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html


 
 This is great! Please keep up the good work, Ant. If this continues, 
 your projects will end up overtaking phobos in terms of pure 
 functionality and all-over object-oriented goodness :-)


for the object oriented - I hope so!


 
 BTW, what was the result of that String discussion a week or so back? 


Seems only I and Kris (from mango) agree.
The functionalities of my String class and his String class are similar.
We want to merge the names of those functionalities, seems we'll go
with verbose naming (ala java) instead the terse names used on phobos.
It's my move now but I'm getting distracted.


 Should we all stick to char[], or can we use a real String class in the 
 future? Inquiring minds want to know 


After the response from Walter (none) I would say vanilla phobos will
never get a String class. It's one the flags Walter shows higher on
D - not needing a String class.


 (... attempting to incorporate dool 
 into another package/project).


dool will grow, if you find something missing just contribute it to dool.

Ant
Dec 05 2004
parent gbatyan yahoo.com writes:
In article <pan.2004.12.06.01.59.07.161474 yahoo.ca>, Ant says...

On Sun, 05 Dec 2004 20:44:45 -0500, Jan Bendtsen wrote:


 Ant wrote:

 This is more a curiosity then anything else
 but I started a document generator from the
 embeded comments on the source code
 (as doxygen or javadoc).
 
 For now it's intergrated with leds but it can be easelly
 decoupled.
 
 see an example at:
 
 http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html


 
 This is great! Please keep up the good work, Ant. If this continues, 
 your projects will end up overtaking phobos in terms of pure 
 functionality and all-over object-oriented goodness :-)


for the object oriented - I hope so!


 
 BTW, what was the result of that String discussion a week or so back? 


Seems only I and Kris (from mango) agree.
The functionalities of my String class and his String class are similar.
We want to merge the names of those functionalities, seems we'll go
with verbose naming (ala java) instead the terse names used on phobos.
It's my move now but I'm getting distracted.


 Should we all stick to char[], or can we use a real String class in the 
 future? Inquiring minds want to know 


After the response from Walter (none) I would say vanilla phobos will
never get a String class. It's one the flags Walter shows higher on
D - not needing a String class.


 (... attempting to incorporate dool 
 into another package/project).


dool will grow, if you find something missing just contribute it to dool.

Ant


See my post, "OO & strings".

what do you think about that?
Dec 07 2004
prev sibling parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Jan Bendtsen wrote:


 BTW, what was the result of that String discussion a week or so back? 


Trenches were dug, a few rounds were fired, and everyone lost. :-P


 Should we all stick to char[], or can we use a real String class in the 
 future? Inquiring minds want to know (... attempting to incorporate dool 
 into another package/project).


D, being a multi-paradigm language, allows you to use both kinds...

If you are using function-data programming, you can use char[] type.
Or wchar[], for Unicode-heavy applications. And dchar for characters.
That is the approach that you will find in Phobos. (or C)

If you are using object-oriented programming, invent a String class.
It'll probably end up using some of the above for the implementation.
That is the approach that you will find in Dool. (or Java)

Which side to choose ? Sorry, can't help you. It's a war, you know...

--anders

PS. What Ant's dool is ? You can read this intro:
     http://dool.sourceforge.net/manifestDool.html
     (it's being used in DUI and leds for instance)
Dec 06 2004
parent John Reimer <brk_6502 yahoo.com> writes:
Anders F Bjφrklund wrote:


 
 D, being a multi-paradigm language, allows you to use both kinds...
 
 If you are using function-data programming, you can use char[] type.
 Or wchar[], for Unicode-heavy applications. And dchar for characters.
 That is the approach that you will find in Phobos. (or C)
 
 If you are using object-oriented programming, invent a String class.
 It'll probably end up using some of the above for the implementation.
 That is the approach that you will find in Dool. (or Java)
 
 Which side to choose ? Sorry, can't help you. It's a war, you know...
 
 --anders
 
 PS. What Ant's dool is ? You can read this intro:
     http://dool.sourceforge.net/manifestDool.html
     (it's being used in DUI and leds for instance)


I tend to agree with Anders here. My opinion is that a String class for 
the OOP side of things would be extremely useful and perhaps even 
preferred.  But people can use it who want to use it.  It doesn't mean 
that char[], wchar[], and dchar[] need to be abandoned.  The procedural 
stylists can keep using them all they want.  That's the way D should 
work... OOP should never be forced.

For myself, I'd prefer to use a String type.  I would leave the char[] 
and friends to the quick programming projects.

If Ant and Kris can get some String ideas put together, I'll support 
their endeavor.

Later,

John
Dec 08 2004
prev sibling parent reply Hiroshi Sakurai <Hiroshi_member pathlink.com> writes:
In article <pan.2004.12.04.16.52.03.782265 yahoo.ca>, Ant says...

This is more a curiosity then anything else
but I started a document generator from the
embeded comments on the source code
(as doxygen or javadoc).

For now it's intergrated with leds but it can be easelly
decoupled.

see an example at:

http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html



Ant


It is expected also in Japan.
Please do your best.
Dec 12 2004
parent reply Ant <duitoolkit yahoo.ca> writes:
On Sun, 12 Dec 2004 10:42:41 +0000, Hiroshi Sakurai wrote:


 In article <pan.2004.12.04.16.52.03.782265 yahoo.ca>, Ant says...

This is more a curiosity then anything else
but I started a document generator from the
embeded comments on the source code
(as doxygen or javadoc).

For now it's intergrated with leds but it can be easelly
decoupled.

see an example at:

http://dui.sourceforge.net/dui_ComboBoxTextEntry_ComboBoxTextEntry.html



Ant


 
 It is expected also in Japan.
 Please do your best.


I'll do my best.

But my best doesn't include UTF-8 :(

I can't see japanese characters on leds...
(any help is welcome)

I just uploaded a test with chars copied from a japanese page:
http://dui.sourceforge.net/dui_PopupBox_PopupBox.html

doesn't look good - doesn't look japanese to me...(?)

the japanese characters should be from the title at
http://www.kmonos.net/alang/d/
but sure looks different.

Ant
Dec 14 2004
parent reply ahiru <asuka h5.dion.ne.jp> writes:
I just uploaded a test with chars copied from a japanese page:
http://dui.sourceforge.net/dui_PopupBox_PopupBox.html

doesn't look good - doesn't look japanese to me...(?)



 <meta http-equiv="Content-Type" content="text/html; charset=shift_jis">


not "shift_jis" but "UTF-8"

<meta http-equiv="Content-Type" content="text/html; charset="UTF-8">
Dec 14 2004
parent reply Ant <Ant_member pathlink.com> writes:
In article <cpmfir$1agr$1 digitaldaemon.com>, ahiru says...

I just uploaded a test with chars copied from a japanese page:
http://dui.sourceforge.net/dui_PopupBox_PopupBox.html

doesn't look good - doesn't look japanese to me...(?)



 <meta http-equiv="Content-Type" content="text/html; charset=shift_jis">


not "shift_jis" but "UTF-8"

<meta http-equiv="Content-Type" content="text/html; charset="UTF-8">


thank you, but,

Did you try it?
It doesn't change a thing for me. Is there something else?

Ant
Dec 14 2004
parent reply ahiru <asuka h5.dion.ne.jp> writes:
In article <cpmugi$208e$1 digitaldaemon.com>, Ant says...

thank you, but,

Did you try it?
It doesn't change a thing for me. Is there something else?


hmm.
i did nothing.

i snapped a screenshot.
http://user.script.nu/~ahiru/encoding_utf-8.png
(windows xp(sp1, ja) and firefox 1.0(en))

did you install a japanese font into your system?
Dec 14 2004
parent reply Ant <Ant_member pathlink.com> writes:
In article <cpnh7p$2rvv$1 digitaldaemon.com>, ahiru says...

In article <cpmugi$208e$1 digitaldaemon.com>, Ant says...

thank you, but,

Did you try it?
It doesn't change a thing for me. Is there something else?


hmm.
i did nothing.

i snapped a screenshot.
http://user.script.nu/~ahiru/encoding_utf-8.png
(windows xp(sp1, ja) and firefox 1.0(en))


Ok, it works if I do that (explicit tell firefox to use UTF-8).
but the original page (http://www.kmonos.net/alang/d/) where I copied
the text from default is at shift_JIS and doesn't work when I change
the encoding to UTF-8.

At least now I know that my String class is working for UTF-8.
thank you.


did you install a japanese font into your system?


Yes, I can see japanese characters on other pages.

Ant
Dec 14 2004
parent reply ahiru <asuka h5.dion.ne.jp> writes:
In article <cpni85$2t7r$1 digitaldaemon.com>, Ant says...

Ok, it works if I do that (explicit tell firefox to use UTF-8).
but the original page (http://www.kmonos.net/alang/d/) where I copied
the text from default is at shift_JIS and doesn't work when I change
the encoding to UTF-8.


ah, i understand now.

http://dui.sourceforge.net/dui_PopupBox_PopupBox.html
this page's char encoding is not "UTF-8", it is "UTF-8N". BOM is lacking.



- ahiru
- ‰pŒκ•ͺ‚©‚θ‚ά‚Ή‚ρBŠ₯ŽŒ‚Α‚Δ‰½‚Ύ‚Α‚―
Dec 14 2004
parent Ant <Ant_member pathlink.com> writes:
In article <cpnlfq$313n$1 digitaldaemon.com>, ahiru says...

In article <cpni85$2t7r$1 digitaldaemon.com>, Ant says...

Ok, it works if I do that (explicit tell firefox to use UTF-8).
but the original page (http://www.kmonos.net/alang/d/) where I copied
the text from default is at shift_JIS and doesn't work when I change
the encoding to UTF-8.


ah, i understand now.

http://dui.sourceforge.net/dui_PopupBox_PopupBox.html
this page's char encoding is not "UTF-8", it is "UTF-8N". BOM is lacking.



- ahiru


Ah... thanks for the reference. I'll see if I can understant all this...

Ant


- ‰pŒκ•ͺ‚©‚θ‚ά‚Ή‚ρBŠ₯ŽŒ‚Α‚Δ‰½‚Ύ‚Α‚―


BTW (I bet you know this)
your signature only shows properly on encoding shitf_JIS
Dec 14 2004