www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - DDoc and comments

reply Ty Tower <tytower hotmail.com.au> writes:
 I notice with DDoc that some new lines are missed  where  comments are
concerned 

here is an example of what is produced

this(Composite parent, int style); 
Constructs a new instance of this class given its parent and a style value
describing its behavior and appearance. 
 The style value is either one of the style constants defined in class DWT
which is applicable to instances of this class, or must be built by bitwise
OR'ing together (that is,  using the int "|" operator) two or more of those DWT
style constants. The class description lists the style constants that are
applicable to the class. Style bits are also inherited from superclasses. 

  param parent a widget which will be the parent of the new instance (cannot be
null)  param style the style of widget to construct 

  exception IllegalArgumentException 
ERROR_NULL_ARGUMENT - if the parent is null
  exception DWTException 
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the
parent


  see DWT#NO_BACKGROUND  see DWT#NO_FOCUS  see DWT#NO_MERGE_PAINTS  see
DWT#NO_REDRAW_RESIZE  see DWT#NO_RADIO_GROUP  see Widget#getStyle 

in the code they are as so
  see DWT#NO_BACKGROUND
  see DWT#NO_FOCUS
  see DWT#NO_MERGE_PAINTS
  see DWT#NO_REDRAW_RESIZE 
  see DWT#NO_RADIO_GROUP 
  see Widget#getStyle
Mar 01 2008
next sibling parent reply "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
"Ty Tower" <tytower hotmail.com.au> wrote in message 
news:fqcsnj$eah$1 digitalmars.com...

 I notice with DDoc that some new lines are missed  where  comments are 
 concerned

 here is an example of what is produced

 this(Composite parent, int style);
 Constructs a new instance of this class given its parent and a style value 
 describing its behavior and appearance.
 The style value is either one of the style constants defined in class DWT 
 which is applicable to instances of this class, or must be built by 
 bitwise OR'ing together (that is,  using the int "|" operator) two or more 
 of those DWT style constants. The class description lists the style 
 constants that are applicable to the class. Style bits are also inherited 
 from superclasses.

  param parent a widget which will be the parent of the new instance 
 (cannot be null)  param style the style of widget to construct

  exception IllegalArgumentException
 ERROR_NULL_ARGUMENT - if the parent is null
  exception DWTException
 ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created 
 the parent


  see DWT#NO_BACKGROUND  see DWT#NO_FOCUS  see DWT#NO_MERGE_PAINTS  see 
 DWT#NO_REDRAW_RESIZE  see DWT#NO_RADIO_GROUP  see Widget#getStyle

 in the code they are as so
  see DWT#NO_BACKGROUND
  see DWT#NO_FOCUS
  see DWT#NO_MERGE_PAINTS
  see DWT#NO_REDRAW_RESIZE
  see DWT#NO_RADIO_GROUP
  see Widget#getStyle


Have you read the DDoc documentation?

http://www.digitalmars.com/d/1.0/ddoc.html

It doesn't use the same syntax as doxygen.
Mar 01 2008
parent reply Ty Tower <tytower hotmail.com.au> writes:
Jarrett Billingsley Wrote:

 Have you read the DDoc documentation?
 http://www.digitalmars.com/d/1.0/ddoc.html
 It doesn't use the same syntax as doxygen. 


 

I suppose you are trying to tell me something but you are not doing well with
that
What do you mean? The documentation does not mention   anywhere in the page !
Mar 01 2008
next sibling parent reply Mike Parker <aldacron71 yahoo.com> writes:
Ty Tower wrote:

 Jarrett Billingsley Wrote:

 Have you read the DDoc documentation?


  > http://www.digitalmars.com/d/1.0/ddoc.html

 It doesn't use the same syntax as doxygen. 


  
 
 I suppose you are trying to tell me something but you are not doing well with
that
 What do you mean? The documentation does not mention   anywhere in the page ! 
 


Both Jarrett and the documentation are telling you something, but you're 
not doing well with grokking it.
Mar 01 2008
parent reply Ty Tower <tytower hotmail.com.au> writes:
Mike Parker Wrote:


 Ty Tower wrote:

 Jarrett Billingsley Wrote:

 Have you read the DDoc documentation?


  > http://www.digitalmars.com/d/1.0/ddoc.html

 It doesn't use the same syntax as doxygen. 


  
 
 I suppose you are trying to tell me something but you are not doing well with
that
 What do you mean? The documentation does not mention   anywhere in the page ! 
 


 Both Jarrett and the documentation are telling you something, but you're 
 not doing well with grokking it.


People who post without reading the previous posts really piss me off
Spend some time and think about the problem first. I know its not your problem
to worry about but I post looking for some sort of answer to my question.

Comments like these while amusing are useless.

Read this --  The  see type comment is included in each of the ".d" files for
dwt and dwt-examples as they have been ported . When I extract the document
portion of them with DDoc  I get the above 

It is not a big problem for me and I am only bringing it up because it is not
quite right.  If somebody is interested to correct this behaviour in DMD  using
the -D switch then I figure this is the place it should be.

I already know that  see does nothing in DDoc ....that is the problem
Mar 01 2008
next sibling parent reply Paul Findlay <r.lph50+d gmail.com> writes:
 It is not a big problem for me and I am only bringing it up because it is
 not quite right.  If somebody is interested to correct this behaviour in
 DMD  using the -D switch then I figure this is the place it should be.


I think DDoc is not going to treat them as needing a line break because
there is no paragraph break. Are you wanting DDoc to interpret them javadoc
style?

It looks like the dwt comments are copied and pasted from some java code

 - Paul
Mar 02 2008
parent reply Jesse Phillips <jessekphillips gmail.com> writes:
On Sun, 02 Mar 2008 21:36:23 +1300, Paul Findlay wrote:


 It is not a big problem for me and I am only bringing it up because it
 is not quite right.  If somebody is interested to correct this
 behaviour in DMD  using the -D switch then I figure this is the place
 it should be.


 I think DDoc is not going to treat them as needing a line break because
 there is no paragraph break. Are you wanting DDoc to interpret them
 javadoc style?
 
 It looks like the dwt comments are copied and pasted from some java code
 
  - Paul


The DWT port is done from the Java files themselves. So it is likely that 
the comments are not getting ported, I am sure there is original D code 
in the port, but it would appear these are just from the original 
document.
Mar 02 2008
parent John Reimer <terminal.node gmail.com> writes:
Jesse Phillips wrote:

 On Sun, 02 Mar 2008 21:36:23 +1300, Paul Findlay wrote:
 

 It is not a big problem for me and I am only bringing it up because it
 is not quite right.  If somebody is interested to correct this
 behaviour in DMD  using the -D switch then I figure this is the place
 it should be.


 I think DDoc is not going to treat them as needing a line break because
 there is no paragraph break. Are you wanting DDoc to interpret them
 javadoc style?

 It looks like the dwt comments are copied and pasted from some java code

  - Paul


 
 The DWT port is done from the Java files themselves. So it is likely that 
 the comments are not getting ported, I am sure there is original D code 
 in the port, but it would appear these are just from the original 
 document.



Yes, they are from the original java files.  In fact, there's 
comparatively little original D code in the port considering the size of 
the project.  Most of it is /lots/ of small changes from the Java source 
(types, boolean expressions, consts, keywords, C bindings), although 
there was a lot of work in translating java mechanisms to D (due to 
language differences in things like overriding and static constructors). 
  This is a good thing because it means tracking future SWT versions 
should not be too difficult.

We haven't touched doc comments yet.  That will have to come later when 
the ports are complete... or if somebody steps up to take on the challenge.

-JJR
Mar 02 2008
prev sibling parent reply Mike Parker <aldacron71 yahoo.com> writes:
Ty Tower wrote:

 Mike Parker Wrote:
 

 Ty Tower wrote:

 Jarrett Billingsley Wrote:

 Have you read the DDoc documentation?


  > http://www.digitalmars.com/d/1.0/ddoc.html

 It doesn't use the same syntax as doxygen. 


  

 I suppose you are trying to tell me something but you are not doing well with
that
 What do you mean? The documentation does not mention   anywhere in the page ! 


 Both Jarrett and the documentation are telling you something, but you're 
 not doing well with grokking it.


 
 People who post without reading the previous posts really piss me off
 Spend some time and think about the problem first. I know its not your problem
to worry about but I post looking for some sort of answer to my question.
 


I'm glad it pissed you off. Now please remember it the next time you 
want to insult someone who is trying to help you. There are several 
friendly people around here who have helped you with DWT and other 
issues, yet you have repeatedly insulted them when their answers to your 
questions didn't get you where you wanted to be. I know that some people 
are ignoring your posts entirely now.

I normally don't post unless I have something to contribute to the 
conversation, but in this case I really wanted to point out that you are 
stretching the limits of tolerance. Please be more considerate in future 
else you'll alienate more people.
Mar 02 2008
parent reply Ty Tower <tytower hotmail.com.au> writes:
Mike Parker Wrote:


 Ty Tower wrote:

 Mike Parker Wrote:
 

 Ty Tower wrote:

 Jarrett Billingsley Wrote:

 Have you read the DDoc documentation?


  > http://www.digitalmars.com/d/1.0/ddoc.html

 It doesn't use the same syntax as doxygen. 


  

 I suppose you are trying to tell me something but you are not doing well with
that
 What do you mean? The documentation does not mention   anywhere in the page ! 


 Both Jarrett and the documentation are telling you something, but you're 
 not doing well with grokking it.


 
 People who post without reading the previous posts really piss me off
 Spend some time and think about the problem first. I know its not your problem
to worry about but I post looking for some sort of answer to my question.
 


 
 I'm glad it pissed you off. Now please remember it the next time you 
 want to insult someone who is trying to help you. There are several 
 friendly people around here who have helped you with DWT and other 
 issues, yet you have repeatedly insulted them when their answers to your 
 questions didn't get you where you wanted to be. I know that some people 
 are ignoring your posts entirely now.
 
 I normally don't post unless I have something to contribute to the 
 conversation, but in this case I really wanted to point out that you are 
 stretching the limits of tolerance. Please be more considerate in future 
 else you'll alienate more people.


In your opinion heh? - the post stands  and applies .People like yourself
should be encouraged not to post because they post on a whim without knowlege
of what they are talking about because they misunderstood the question.
You did not read the previous material and it shows .

If my comments offend you then don't read them -I'll take my chances.
Mar 02 2008
parent Bill Baxter <dnewsgroup billbaxter.com> writes:
Ty Tower wrote:

 Mike Parker Wrote:
 

 Ty Tower wrote:

 Mike Parker Wrote:


 Ty Tower wrote:

 Jarrett Billingsley Wrote:

 Have you read the DDoc documentation?


  > http://www.digitalmars.com/d/1.0/ddoc.html

 It doesn't use the same syntax as doxygen. 


  

 I suppose you are trying to tell me something but you are not doing well with
that
 What do you mean? The documentation does not mention   anywhere in the page ! 


 Both Jarrett and the documentation are telling you something, but you're 
 not doing well with grokking it.


 People who post without reading the previous posts really piss me off
 Spend some time and think about the problem first. I know its not your problem
to worry about but I post looking for some sort of answer to my question.


 I'm glad it pissed you off. Now please remember it the next time you 
 want to insult someone who is trying to help you. There are several 
 friendly people around here who have helped you with DWT and other 
 issues, yet you have repeatedly insulted them when their answers to your 
 questions didn't get you where you wanted to be. I know that some people 
 are ignoring your posts entirely now.

 I normally don't post unless I have something to contribute to the 
 conversation, but in this case I really wanted to point out that you are 
 stretching the limits of tolerance. Please be more considerate in future 
 else you'll alienate more people.


 
 In your opinion heh? - the post stands  and applies .People like yourself
should be encouraged not to post because they post on a whim without knowlege
of what they are talking about because they misunderstood the question.
 You did not read the previous material and it shows .
 
 If my comments offend you then don't read them -I'll take my chances.


Many of the question you have asked really have been vague, Ty.  People 
are trying to answer the best they can with the scanty information you 
are giving them.  Not because they have to, but out of the kindness of 
their hearts.  And when they happen to be wrong, you lash back at them. 
  Welcome to planet earth.  People have their own lives here, which 
don't happen to revolve around you and your needs.  Please forgive us 
for not dropping everything and catering to your every beck and call and 
reading every post of yours forwards and backwards five times looking 
for hidden clues.

Anyway, if you haven't gathered by now, the   comments you see in DWT 
are there because the source was translated from Java and the comments 
just haven't been fixed to be DDoc syntax yet.

If you'd like to lash back at me for this reply, then I will be happy to 
cease all correspondence with you until you can learn some manners.

Regards,
--bb
Mar 02 2008
prev sibling parent reply "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
"Ty Tower" <tytower hotmail.com.au> wrote in message 
news:fqdadg$1hq9$1 digitalmars.com...

 Jarrett Billingsley Wrote:

 Have you read the DDoc documentation?
 http://www.digitalmars.com/d/1.0/ddoc.html
 It doesn't use the same syntax as doxygen.



 I suppose you are trying to tell me something but you are not doing well 
 with that
 What do you mean? The documentation does not mention   anywhere in the 
 page !


Stop being an ingrateful ass to everyone.  Seriously.  People try to help 
you and you make fun of them?  Get over yourself.

As has been mentioned, I don't know how many times by now, stuff like  param 
means nothing to DDoc, and it's why it's not mentioned anywhere on the 
specification page.

As for why something like this:

  see DWT#NO_BACKGROUND
  see DWT#NO_FOCUS
  see DWT#NO_MERGE_PAINTS
  see DWT#NO_REDRAW_RESIZE
  see DWT#NO_RADIO_GROUP
  see Widget#getStyle

becomes:

  see DWT#NO_BACKGROUND  see DWT#NO_FOCUS  see DWT#NO_MERGE_PAINTS  see 
DWT#NO_REDRAW_RESIZE  see DWT#NO_RADIO_GROUP  see Widget#getStyle

It's because whitespace is ignored in HTML when you view the result in a web 
browser.  The compiler outputs that first block of text exactly as it 
appears, but your browser will render it without linebreaks because, well, 
that's how HTML works.  If you were to open the HTML file in a text editor 
or view the source in your browser, you'd see that the text still has the 
linebreaks in it.

Don't bother replying with some other scathing remark.  You're not going to 
impress anyone by being a douchebag.
Mar 02 2008
parent reply Ty Tower <tytower hotmail.com.au> writes:
Jarrett Billingsley Wrote:
and did nothing for the question except show what an ass says regularly

Read again and you will see I understand all the comments but re-read the
original post.
It is intended to point out that there is a correction needed there when
someone gets around to doing it becaulse DDoc does not produce accurate output
in this regard arsehole!
Mar 02 2008
parent reply Derek Parnell <derek nomail.afraid.org> writes:
On Sun, 02 Mar 2008 22:23:21 -0500, Ty Tower wrote:


 Read again and you will see I understand all the comments but re-read the
original post.
 It is intended to point out that there is a correction needed there when
someone
 gets around to doing it becaulse DDoc does not produce accurate output in this
 regard


Dear Mr Tower,
thank you for your kind interest in this subject. As you so rightfully
pointed out there does need to be some corrections made, but as it happens
to turn out, the correction must be applied to the documentation text and
not DDoc itself. The current documentation, as was mentioned by others, is
a legacy of the application being ported, and has not yet undergone
conversion to the DDoc format. We apologize for this inconvenience and have
noted it to be fixed as the earliest appropriate opportunity.

With respect, we reluctantly point out that DDoc is in fact producing
correct output, given the input it has. 

And by the way, all this was politely said to you before, only four hours
after your initial post, by Mr Paul Findlay, so we are a little perplexed
about your assertion that "I understand all the comments".

Thank for you again for your interest. 

==== MESSAGE ENDS ====

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
3/03/2008 3:03:05 PM
Mar 02 2008
parent reply Jesse Phillips <jessekphillips gmail.com> writes:
On Mon, 03 Mar 2008 15:18:16 +1100, Derek Parnell wrote:


 On Sun, 02 Mar 2008 22:23:21 -0500, Ty Tower wrote:
 

 Read again and you will see I understand all the comments but re-read
 the original post. It is intended to point out that there is a
 correction needed there when someone gets around to doing it becaulse
 DDoc does not produce accurate output in this regard


 
 Dear Mr Tower,
 thank you for your kind interest in this subject. As you so rightfully
 pointed out there does need to be some corrections made, but as it
 happens to turn out, the correction must be applied to the documentation
 text and not DDoc itself. The current documentation, as was mentioned by
 others, is a legacy of the application being ported, and has not yet
 undergone conversion to the DDoc format. We apologize for this
 inconvenience and have noted it to be fixed as the earliest appropriate
 opportunity.
 
 With respect, we reluctantly point out that DDoc is in fact producing
 correct output, given the input it has.
 
 And by the way, all this was politely said to you before, only four
 hours after your initial post, by Mr Paul Findlay, so we are a little
 perplexed about your assertion that "I understand all the comments".
 
 Thank for you again for your interest.
 
 ==== MESSAGE ENDS ====


Derek,
I am sorry to say that reason does not work. If you wish there are a 
great many attempts in the digtialmars.dwt group, and thus I am only 
feeling sorry for those that attempt polite corrections to towers 
statements.
Mar 02 2008
parent reply John Reimer <terminal.node gmail.com> writes:
Jesse Phillips wrote:

 On Mon, 03 Mar 2008 15:18:16 +1100, Derek Parnell wrote:
 

 On Sun, 02 Mar 2008 22:23:21 -0500, Ty Tower wrote:


 Read again and you will see I understand all the comments but re-read
 the original post. It is intended to point out that there is a
 correction needed there when someone gets around to doing it becaulse
 DDoc does not produce accurate output in this regard


 Dear Mr Tower,
 thank you for your kind interest in this subject. As you so rightfully
 pointed out there does need to be some corrections made, but as it
 happens to turn out, the correction must be applied to the documentation
 text and not DDoc itself. The current documentation, as was mentioned by
 others, is a legacy of the application being ported, and has not yet
 undergone conversion to the DDoc format. We apologize for this
 inconvenience and have noted it to be fixed as the earliest appropriate
 opportunity.

 With respect, we reluctantly point out that DDoc is in fact producing
 correct output, given the input it has.

 And by the way, all this was politely said to you before, only four
 hours after your initial post, by Mr Paul Findlay, so we are a little
 perplexed about your assertion that "I understand all the comments".

 Thank for you again for your interest.

 ==== MESSAGE ENDS ====


 
 Derek,
 I am sorry to say that reason does not work. If you wish there are a 
 great many attempts in the digtialmars.dwt group, and thus I am only 
 feeling sorry for those that attempt polite corrections to towers 
 statements.



Er... you did notice that Derek's response was tongue-in-cheek?

Derek managed to catch the nature of this whole situation perfectly with 
his company-complaints-department response.  Perhaps, with this letter, 
Derek has saved our product from catastrophic failure?

I don't know what we'd do without all the profits coming in, so tip of 
the hat to you, Derek. ;)

-JJR
Mar 03 2008
parent reply John Reimer <terminal.node gmail.com> writes:
Ty Tower wrote:

 John Reimer Wrote:
 

 Jesse Phillips wrote:

 On Mon, 03 Mar 2008 15:18:16 +1100, Derek Parnell wrote:




 

 -JJR


 
 I think you blokes are a pack of nutters. You lick each others arses at every
opportunity and obviously dont like anybody pointing out something that is most
obviously wrong.
 
 Work it out as to whether DDoc is responsible or the code in dwt is to blame
.Either way what should come out is a copy of what goes in
 
 It goes in with a line break and it comes out without one. Fairly simple stuff
and if you don't want to fix it that's fine with me .
 
 If I see something that seems wrong I will continue to post. 
 
 You poofs can go play with each other ,I couldn't care less . Though I would
shoot you at the first opportunity. One day there might just be such an
opportunity.
 



I shouldn't answer this, but I just want to point out that my last "clap 
on the back" to Derek was probably an indiscretion.  Unfortunately, his 
parody was just somehow appropriate to the situation. I'm sorry that it 
was at your expense.

If we seem like a close bunch... well, to some extent, some of us have 
been through a fair bit of D's "tumultuous" evolution over the last 5 
years, so it's rather hard not to maintain some sort of comradry after 
all that.

I'm afraid, though, your uncouth statements are making me wish that 
there were some sort of moderation here.  I'm completely surprised you 
get away with saying what you do.  I don't think D has ever had quite 
your kind before.  Or maybe I'm just forgetting. I suppose that this 
should be taken as a positive indication of D's growth.

-JJR
Mar 03 2008
next sibling parent Ty Tower <tytower hotmail.com.au> writes:
John Reimer Wrote:


Impressed with your remarkable restraint John. I'll try harder and I follow
your drift
Mar 03 2008
prev sibling parent Frank Benoit <keinfarbton googlemail.com> writes:
John Reimer schrieb:

 I shouldn't answer this, ...
Mar 04 2008
prev sibling parent Paul Findlay <r.lph50+d gmail.com> writes:
  I notice with DDoc that some new lines are missed  where  comments are
  concerned


DDoc isn't an implementation of Javadocs.
So, you will find  see,  param etc. do not do anything special.
Instead there are different ways of doing it in DDoc.

http://www.digitalmars.com/d/1.0/ddoc.html has (some) details.


   param parent a widget which will be the parent of the new instance
  (cannot be null)  param style the style of widget to construct


Try something like:
/**
 * Params:
 *      parent =  a widget which will be the parent of the new instance
 *                (cannot be null)
 *      style =   style the style of widget to construct
 */


   exception IllegalArgumentException
 ERROR_NULL_ARGUMENT - if the parent is null


/**
 * Throws: IllegalArgumentException if the parent is null
 */


   see Widget#getStyle


Not too sure, something like:
/**
 * See_Also:
 *    Widget.getStyle
 */
?

 - Paul
Mar 01 2008