between and among: worth Phobosization?

[H. S. Teoh]

On Tue, Dec 17, 2013 at 12:50:21AM +0100, digitalmars-d-bounces at puremagic.com wrote:
> On Monday, 16 December 2013 at 23:01:36 UTC, Walter Bright wrote:
> >I hate to say it, but often when I read the Phobos library
> >documentation I wind up having to check the source code. Yes, I
> >should follow my own advice and do PRs.
> 
> You should consider having direct links to html-formatted source
> code from the documentation. Like this:
> 
> http://webapp-improved.appspot.com/api/webapp2_extras/json.html
> 
> I find that simple "[source]"-link to be a very helpful solution. It
> is very difficult to make good enough documentation to cover things
> like assumptions that you need to know about when doing inheritance
> related stuff. So easy access to code is very nice, and that also
> means that the real documentation can be less detailed and verbose
> and easier to comprehend.

I agree it's a nifty trick, but I think it's solving the wrong problem.
Documentation should document the *API*, and user code shouldn't depend
on quirks in the current implementation, because it may change later
(bugfixes, optimizations, etc.).


T

-- 
You have to expect the unexpected. -- RL