August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Hasan Aljudy | "Hasan Aljudy" <hasan.aljudy@gmail.com> wrote in message news:deprnl$vqb$1@digitaldaemon.com... > One objection: the first form of param documentation looks ugly (to me): > void foo( > int x, // is for this > int y // is for that > ) Yes, that doesn't look too hot even though it is more "pure", which is why I reluctantly decided to add the Params: section. > And for the 'Deprecated', it seems redundant, the compiler already knows the function is deprecated. Right, but there isn't an obvious way to automatically associate an explanation with it. For example, a more user friendly compiler could issue along with a deprecation error message the contents of the Deprecated: section. > /** > Use bar() instead > */ > deprecated void foo() { ... } > > Embedded HTML doesn't look very good :/ I know, that's why for conventional documentation it won't be necessary. It's only there for people who absolutely need to do something extra and for me to avoid having to add endless features to the documentation extractor. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Ben Hinkle | Ben Hinkle wrote: > [snip] > >>(and is mostly similiar to that proposal). Is it because just the @ symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) wth.. what's so ugly about the AT symbol? :o > > > @because @human-readable @text @doesn't @have @ats @in @it > ...Huh? What: you: said: does: not: make: sense: at: all: Certainly you don't think we are to put marker symbols (whatever they be) in every word of the comment documentation, which is what you implied. Please restate. -- Bruno Medeiros Computer Science/Engineering student |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Bruno Medeiros | "Bruno Medeiros" <daiphoenixNO@SPAMlycos.com> wrote in message news:deq5e5$1lrp$1@digitaldaemon.com... > Speaking of which, and considering what Walter said on the other thread( "I only disagree with the form that C# and Javadoc take, as they are needlessly and excessively klunky." ), what is the problem with Javadoc? ? I too agree that C# doc style seems clunky, but Javadoc's seems pretty ok to me (and is mostly similiar to that proposal). Is it because just the @ symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) wth.. what's so ugly about the AT symbol? :o javadoc isn't bad. It's those ugly @ symbols <g>, which you'd never see in written documentation. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Bruno Medeiros | "Bruno Medeiros" <daiphoenixNO@SPAMlycos.com> wrote in message news:deqd0j$1rq5$1@digitaldaemon.com... > Ben Hinkle wrote: >> [snip] >> >>>(and is mostly similiar to that proposal). Is it because just the @ symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) wth.. what's so ugly about the AT symbol? :o >> >> >> @because @human-readable @text @doesn't @have @ats @in @it >> > > ...Huh? What: you: said: does: not: make: sense: at: all: > > Certainly you don't think we are to put marker symbols (whatever they be) in every word of the comment documentation, which is what you implied. Please restate. I was using "dramatic license" to make my point. For a more serious answer look around you in the real world at forms containing information like application forms or bills and you'll see stuff like address: 7 blah blah St phone: 123-456-7890 account number: 1 Using : is a standard clue to humans. Using @ is great for computers but isn't natural for humans. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Ben Hinkle | Ben Hinkle wrote:
>
> Using : is a standard clue to humans. Using @ is great for computers but isn't natural for humans.
>
>
But on the other hand, once you've worked with Java for a while the @ symbols don't bother you at all. In fact, they stand out when perusing the source and pull your eyes to the important parts of the documentation. Not that I'm saying we should have them in D, but they really aren't all bad.
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Ben Hinkle | Ben Hinkle wrote: > @because @human-readable @text @doesn't @have @ats @in @it I've probably just spent far too much time working in MOO-based environments, but that was fairly readable to me... Of course I'm also used to typing out command lines like: @@sweep @players() has prop {@($attrs.notable),@($ftr_attr.notable)} @@who! @last with sort_ip So don't go by me. :) Although one could "wrap" id's in @'s. Aka: @ident@ text more text -- Chris Sauls |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Mike Parker | In article <deqfvm$1upi$1@digitaldaemon.com>, Mike Parker says... > >Ben Hinkle wrote: > >> >> Using : is a standard clue to humans. Using @ is great for computers but isn't natural for humans. >> >> >But on the other hand, once you've worked with Java for a while the @ symbols don't bother you at all. In fact, they stand out when perusing the source and pull your eyes to the important parts of the documentation. Not that I'm saying we should have them in D, but they really aren't all bad. Speaking of javadoc, I hope we're not reinventing the wheel here. Both javadoc and doxygen use a well known documentation syntax. Doxygen even supports d (not completely though) already. I really hope a working doxygen support is everything we ever need. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to James Dunne | "James Dunne" <james.jdunne@gmail.com> wrote in message news:deq9tp$1pjj$1@digitaldaemon.com... > It was mentioned that identifiers would automatically be emphasized. I'm wondering if that would get annoying if you had a class member named 'a' or some > other common english term that you'd use in your docs... I think a special > marker character should be used to deliniate identifiers from regular documentation. It doesn't have to be @. How about placing parens or curlies > around it? That could be a problem, and it probably *would* discourage giving parameters names like 'a'. This might not be a bad thing. But in the doc it does mention that prefixing a name with a '_' would disable emphasizing it, and the '_' would be stripped. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Ben Hinkle | "Ben Hinkle" <ben.hinkle@gmail.com> wrote in message news:deqf9e$1ugt$1@digitaldaemon.com... > I was using "dramatic license" to make my point. For a more serious answer look around you in the real world at forms containing information like application forms or bills and you'll see stuff like > > address: 7 blah blah St > phone: 123-456-7890 > account number: 1 > > Using : is a standard clue to humans. Using @ is great for computers but isn't natural for humans. Using a postfix : isn't any harder for computers, so the argument for @ just falls away. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Chris Sauls | "Chris Sauls" <ibisbasenji@gmail.com> wrote in message news:deqin5$21ts$1@digitaldaemon.com... > So don't go by me. :) Although one could "wrap" id's in @'s. Aka: > > @ident@ text > more text Sure, you could, but ... <g> I used @ in the first language I wrote (ABEL). It just never looked good. |
Copyright © 1999-2021 by the D Language Foundation