www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Please remove misleading examples from D's website

reply Mehrdad <wfunction hotmail.com> writes:
Please remove this from the home page:
     // Automatic or explicit memory management
     delete cl;
It is obviously not doing what it implies.

Similarly, please remove "Allocating Class Instances On The Stack" from 
the memory.html page:
     scope c = new C();   // c is allocated on the stack

These are _not_ simply problems with "keeping documentation up to date". 
Sure, things change, and it's reasonable to expect delays. But these 
have been up for a long enough time, and it is time that they be removed 
-- otherwise they simply mislead the reader and claim that D has 
capabilities which it doesn't actually have. (If there are substitutes 
for these, they should be substituted instead. If not, or if there isn't 
enough time to write their documentation yet, then such examples should 
be completely removed from the website altogether. But keeping them 
serves no purpose other than misleading the reader.)

Thanks!
Nov 29 2011
next sibling parent maarten van damme <maartenvd1994 gmail.com> writes:
I don't know about the examples you mentioned but I agree. Last time I
tried shared still didn't work and having not working examples not only
leads to a lot of confusion but also on people disliking a perfectly fine
language
Nov 30 2011
prev sibling next sibling parent reply Trass3r <un known.com> writes:
Mehrdad Wrote:

 Please remove this from the home page:
      // Automatic or explicit memory management
      delete cl;
 It is obviously not doing what it implies.
 
 Similarly, please remove "Allocating Class Instances On The Stack" from 
 the memory.html page:
      scope c = new C();   // c is allocated on the stack


Feel free to open a pull request.
Nov 30 2011
parent reply Mehrdad <wfunction hotmail.com> writes:
On 11/30/2011 5:33 AM, Trass3r wrote:

 Mehrdad Wrote:

 Please remove this from the home page:
       // Automatic or explicit memory management
       delete cl;
 It is obviously not doing what it implies.

 Similarly, please remove "Allocating Class Instances On The Stack" from
 the memory.html page:
       scope c = new C();   // c is allocated on the stack


 Feel free to open a pull request.


(1) No idea how :(
(2) Won't get the chance for at least another couple of weeks :(

Thanks for the suggestion though.
Nov 30 2011
parent Trass3r <un known.com> writes:
 Feel free to open a pull request.


 (1) No idea how :(


For small and fast edits github provides a nifty feature:  
https://github.com/blog/844-forking-with-the-edit-button
Nov 30 2011
prev sibling parent reply Dejan Lekic <dejan.lekic gmail.com> writes:
No please! Do not remove, but add a note that those are either deprecated or 
removed and what a developer should do with a modern implementation of D2!
Nov 30 2011
parent reply Mehrdad <wfunction hotmail.com> writes:
On 11/30/2011 7:07 AM, Dejan Lekic wrote:

 No please! Do not remove, but add a note that those are either deprecated or
 removed and what a developer should do with a modern implementation of D2!


Uhm, what?

"Deprecated" means that the feature is still usable, but discouraged.

'delete' and 'scope' (the storage class) are no longer available; they 
simply *don't work*. Marking them as deprecated would be lying to the 
user. They need to be removed entirely.
Nov 30 2011
next sibling parent Timon Gehr <timon.gehr gmx.ch> writes:
On 11/30/2011 05:04 PM, Mehrdad wrote:

 On 11/30/2011 7:07 AM, Dejan Lekic wrote:

 No please! Do not remove, but add a note that those are either
 deprecated or
 removed and what a developer should do with a modern implementation of
 D2!


 Uhm, what?

 "Deprecated" means that the feature is still usable, but discouraged.

 'delete' and 'scope' (the storage class) are no longer available; they
 simply *don't work*. Marking them as deprecated would be lying to the
 user. They need to be removed entirely.


iirc the scope storage class can be used to prevent heap allocation of 
closures.
Nov 30 2011
prev sibling parent reply Dejan Lekic <dejan.lekic gmail.com> writes:
The reason why i wrote what i wrote is simple - so people who read legacy D 
code understand it has been removed or deprecated.
Nov 30 2011
parent reply Hans Uhlig <hans.uhlig teamaol.com> writes:
On 11/30/2011 9:53 AM, Dejan Lekic wrote:

 The reason why i wrote what i wrote is simple - so people who read legacy D
 code understand it has been removed or deprecated.


Then we need documentation versioning. Choose your version and get the 
current documentation. Things not in the current version shouldn't exist 
in its documentation.
Nov 30 2011
parent reply Dejan Lekic <dejan.lekic gmail.com> writes:
 Then we need documentation versioning. Choose your version and get the
 current documentation. Things not in the current version shouldn't exist
 in its documentation.


Again I disagree. Deprecated and/or removed things should be in every 
documentation. Perhaps a whole section called "Removed and deprecated" where 
all such things are listed in, say, chronological order?
Dec 01 2011
parent "Marco Leise" <Marco.Leise gmx.de> writes:
Am 01.12.2011, 09:34 Uhr, schrieb Dejan Lekic <dejan.lekic gmail.com>:


 Then we need documentation versioning. Choose your version and get the
 current documentation. Things not in the current version shouldn't exist
 in its documentation.


 Again I disagree. Deprecated and/or removed things should be in every
 documentation. Perhaps a whole section called "Removed and deprecated"  
 where
 all such things are listed in, say, chronological order?


That sounds better. I also prefer those removed features to be out of view  
as a section below the rest, or as a new page.
Dec 01 2011