On 19 December 2014 at 19:12, Walter Bright via Digitalmars-d <digitalmars-d@puremagic.com> wrote: > On 12/18/2014 2:24 AM, Manu via Digitalmars-d wrote: >> >> Docs need to have examples which are plain and obvious, and the >> language will be absorbed by osmosis. > > > I agree. Can you point to specific cases that need an example?
In this case, my colleague felt it was hard to understand the string functions, but he got through it (after sending me txt messages to ask questions). I recall making the same comments when I first started trying to do string manipulation in D. My personal take is, string functions are all templates, which makes them look more complex than they are, and for me, it was really hard to understand where to look for certain functions; they're spread fairly evenly across 5 or so different modules. Algorithm, range, ascii, uni, utf. Some of the most important functions are in range and algorithm. Perhaps those that are fairly string specific from range/algorithm should have aliases in std.string, or std.string might public import some of the minor modules, like ascii/uni/utf? Like I said in the first post, documentation wasn't a deal breaker, but it was the source of the most commentary. I think it's an area for general improvement, and I would start by reconsidering the basic formatting for reducing noise and improving clarity of the simple details, while the advances and less important details (like contracts) may fade into the background a little. I think a good goal is: At a glance, the function reference that stands out is the name, summary, and what arguments it accepts. The next thing is the detail for each argument and return value. Template args, which throughout phobos are rarely of any 'functional' relevance, need to be toned down so they don't interfere with your initial glance to understand the function and what it does. Most of the time the template args are just some 'T', allowing the function to work with multiple types - particular on strings and algorithms. This is not particularly interesting information, and it shouldn't distract from the important details. Occasionally, there is a template arg that IS a relevant part of the API... I'm not sure how this should be highlighted. Perhaps a subtle visual distinction could be made for template args like 'T' which are just used in the runtime arg list, and template args that don't appear anywhere else, ie, they supply important function arguments. I think there's probably room for some clever design in that space. Finally, contracts are overwhelming, and it's also a feature of D that nobody has seen before. When someone new to D encounters a contract in the docs, they no longer trust their ability to usefully interpret the documentation, and almost certainly become confused; nobody expects to see an 'if' statement in a function declaration. I think that's a shame. The contract usually has no impact on using the function, or how it should be understood, is just applies some limitations to it's genericity. I think contracts should be disconnected and listed separately, as additional information, or with some subtext that makes it obvious what that often confusing bit of text actually means. Ironically, the string and algorithm functions are probably the worst offenders, but coincidentally, there is a high chance that these are the first functions anyone will ever reach for, so they present a terrible first impression.