[Issue 9469] New: Keywords list could use linkage; more-humane documentation

February 07, 2013

Posted by Wyatt

Permalink

Wyatt

Permalink

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

           Summary: Keywords list could use linkage; more-humane
                    documentation
           Product: D
           Version: D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: websites
        AssignedTo: nobody@puremagic.com
        ReportedBy: wyatt.epp@gmail.com


--- Comment #0 from Wyatt <wyatt.epp@gmail.com> 2013-02-07 03:34:38 PST ---
The list at http://dlang.org/lex.html#Keyword is long and flat. It would be well-served by linking to relevant documentation entries for each keyword in cases where that exists. (Things like interface, mixin, pragma, scope, et al). The goal is to make navigating the documentation less error-prone for newcomers.

As an additional consideration, it would be nice if each item in that list had (at least) a short, single sentence, description.  Keywords with zero context often fail to indicate what they interact with, which impedes language acquisition. (e.g. it simplifies questions like "What does 'synchronized' even do?").

To some extent, I feel the keywords deserve their own page. (In-addition-to if
not instead-of a flat list on the lexical page.)  Simply finding the list is
more difficult than it needs to be, as there are no top-level anchors for the
Lexical page and the keyword anchor is simply mixed in with the list of tokens.
 Going this direction, it would probably be helpful to also arrange them
according to their documentation section for reinforcement.

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

Forums