http://d.puremagic.com/issues/show_bug.cgi?id=677

           Summary: [Tracker] Get the documentation cleaned up for 1.0
           Product: D
           Version: 0.177
          Platform: All
        OS/Version: All
            Status: NEW
          Keywords: spec
          Severity: blocker
          Priority: P2
         Component: www.digitalmars.com
        AssignedTo: bugzilla@digitalmars.com
        ReportedBy: smjg@iname.com
 BugsThisDependsOn: 39,40,265,567,576,577,603,612,631,632,633


This tracker continues where issue 511 left off.  With 1.0 around the corner, some serious work is still needed to get the language specification cleaned up.

If you find any issue with the D documentation that you feel should be fixed in time for 1.0, please make this issue depend on it.  Holes, ambiguities, contradictions, undocumented features, typos, you name it.

If it's an instance in which compiler behaviour doesn't match the spec, but you think the compiler is doing what Walter intended and the spec just doesn't say it right, by all means add it.  DDoc issues that are root causes of holes in the Phobos documentation may also be included.

This will help to prioritise issues surrounding the language spec, which must be fixed up before a compiler can be compliant.  Then, as these spec problems are fixed, we will know for sure how any compiler problems related to these issues should be fixed.


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=677





------- Comment #1 from arkangath@gmail.com  2007-02-09 12:43 -------
Created an attachment (id=98)
 --> (http://d.puremagic.com/issues/attachment.cgi?id=98&action=view)
Proposed new file.d

In this file I include the output of the "diff -uN" of file.d against std/file.d


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=677





------- Comment #2 from arkangath@gmail.com  2007-02-09 12:44 -------
(From update of attachment 98)
This is a corrected version of phobos' file implementation. Syntax has been
corrected to conform to http://www.digitalmars.com/d/dstyle.html DDoc comments
have been updated however are not complete yet. I'd like to know if these
corrections  are suitable or if I have touched things that shouldn't have been
touched. I intend to check other files of Phobos, so feedback is appreciated.


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=677





------- Comment #3 from smjg@iname.com  2007-02-09 14:08 -------
This is a tracker issue.  Patches or other contributions of code should not be attached here.  Instead, they should have bug reports of their own.

To attach patches to a tracker makes it impossible to track whether they've been folded in.


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=677





------- Comment #4 from smjg@iname.com  2007-02-09 14:31 -------
Moreover, if you're going to include a diff, then including one that's as big
as the code file or bigger is practically useless.  There are two reasons for
having diffs:
(a) to save disk space/bandwidth by storing/transmitting only the changes to a
document rather than the whole updated document
(b) to draw the human reader's attention to which bits have actually changed

By changing the indentation style as well as fixing up the content, you have created a diff file that's bigger than either version of the code.  What's more, we have a hard time finding the bits where you've actually changed the content among the mass of indentation fixes.  Hence both benefits are lost.

On this basis, it would have made more sense to upload just your updated version of the page.  You could, however, have gained benefit (b) by fixing the indentation first and then diffing between this intermediate version and that with your content fixes put in.


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=677


Brad Roberts <braddr@puremagic.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
  Attachment #98 is|0                           |1
           obsolete|                            |




--- Comment #5 from Brad Roberts <braddr@puremagic.com>  2009-06-07 15:58:53 PDT ---
(From update of attachment 98)
Due to time and feedback, marking this patch obsolete.  If you think the
changes are still useful, please resubmit the changes in a new bug report, not
against this tracker bug.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=677





--- Comment #6 from Stewart Gordon <smjg@iname.com>  2009-06-07 16:06:29 PDT ---
That attachment already has a "new" bug report: bug 944.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------