[Issue 17856] New: __traits( identifier ) could use examples in on line documentation.

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=17856

          Issue ID: 17856
           Summary: __traits( identifier )  could use examples in on line
                    documentation.
           Product: D
           Version: D2
          Hardware: All
               URL: http://dlang.org/
                OS: All
            Status: NEW
          Severity: minor
          Priority: P3
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: kheaser at gmail.com

Here's a transcript of Learn Forum on Dlang.org  Also maybe throw in
definitions for symbols and identifiers in the Glossary section?


On Mon, Sep 25, 2017 at 05:28:13AM +0000, WhatMeForget via Digitalmars-d-learn
wrote:
> 
> This is taken exactly from the traits documentation.
> 
> ------------------------------------------------
> 
> 25 Traits
> 
> 25.21 identifier
> 
> Takes one argument, a symbol. Returns the identifier for that symbol as a string literal.
> 
> ------------------------------------------------
> 
> 
> There are no examples. My naive brain keeps thinking that a symbol and an identifier are the same things.  Can someone give me good definitions of "symbol" and "identifier".   And maybe an example if it is not too much trouble.

You're not the only one.  I stared at this same piece of documentation for a
long time before I figured out what it meant. This is another example of poor
documentation writing.  Please file a bug, and I'll see if I can get around to
making an example for it.

H. S. Teoh


Think of the identifier as the name for the symbol and the symbol as what the
compiler is actually operating on. Typically, a symbol either has a type or is
a type, whereas an identifier is just a name. For instance, when the compiler
sees an identifier in your code, it has to look it up to figure out what its
corresponding symbol is (and you'll get a compiler error if it can't figure out
which symbol you mean - be it because there is no such symbol, the symbol
hasn't been imported, the symbol is inaccessible, or because there are multiple
symbols that you could be refering to, and there isn't enough information for
it to know which you meant).

Regardless, there really should be more examples on that page.

- Jonathan M Davis

--