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