On Tue, Dec 17, 2013 at 12:50:21AM +0100, [email protected] 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
