Is enum static?

[Jonathan M Davis]

On Thursday, August 08, 2013 16:05:24 H. S. Teoh wrote:
> On Thu, Aug 08, 2013 at 06:47:48PM -0400, Jonathan M Davis wrote:
> > On Thursday, August 08, 2013 15:40:25 H. S. Teoh wrote:
> > > Are we going to fix this anytime soon (or at all)? If not, we'd
> > > better start documenting this, since currently enums are being sold
> > > as manifest constants, and most people would understand that as
> > > meaning it's only allocated once at compile-time/startup-time. It
> > > would leave a very bad impression if new users unknowingly end up
> > > with a lot of unwanted allocations just from using a language
> > > feature as-advertised.
> > 
> > There's nothing to fix. It's by design. That _is_ what a manifest
> > constant is as far as D is concerned. And if you search for manifest
> > constants online, you end up running into stuff that talks about
> > #define in C, which does the same thing. So, I don't think that we're
> > doing anything abnormal here. We just have to make sure that it's
> > clear in the documentation that that's how manifest constants work. I
> > don't know what the documentation currently says though.
> 
> [...]
> 
> Seriously, I think we should hire a tech writer. The way we manage our
> docs just ... leaves a lot to be desired. It's very unclear to
> newcomers, and even to someone who's been working with D for a while,
> like myself.
> 
> In fact, I'm going to update http://wiki.dlang.org/Declaring_constants
> right now, to reflect this caveat. Maybe I'll submit a pull for the
> language docs.
> 
> But honestly, I can totally understand why many people find D docs very
> frustrating. In fact, I found the online docs so unhelpful when I first
> found D, that it delayed my adopting D for at least half a year until
> one day I saw TDPL in a local bookstore and decided to buy it. A friend
> of mine has told me, in private, that after trying out D he liked the
> language, but one of the things he decidedly did NOT like was the docs.
> I think the only real solution to this is to hire a full-time tech
> writer to do the documentation, and do it *properly*. We're doing a
> great language a great disservice by documenting it so poorly.

A lot of the problem stems from the fact that most of the devs don't do 
anything with the documenation. We tend to focus on the code and forget about 
the documentation. Maybe we need someone to champion the documentation and at 
least organize what needs to be done with it if not take the time themselves 
to fix it.

The other big issue would probably be the fact that it's also treated as the 
spec for the language, and you don't write the same kind of documentation when 
you're writing a spec as when you're writing something to teach people (not 
that D's docs are quite what a spec requires either, as they don't tend to be 
precise enough, but they tend to lean heavily in that direction and aren't 
even vaguely meant as tutorials).

- Jonathan M Davis