"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.

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

"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.

"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.

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.

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

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.

"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.

"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.

"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.