Library Documentation

[Jonathan M Davis]

On Friday, March 11, 2011 19:31:51 Nicholas wrote:
> == Quote from Jonathan M Davis (jmdavisProg at gmx.com)'s article
> 
> > On Friday, March 11, 2011 12:08:19 Nicholas wrote:
> > > == Quote from novice2 (sorry at noem.ail)'s article
> > > 
> > > > Nicholas Wrote:
> > > > > As a result of (my) complaining and being a huge fan of XMind, I
> > > > > decided to try to organize the library for my own references as I
> > > > > encounter new sections of it.  I have a decent portion of it in
> > > > > place now.  I thought I'd post a link in case it can help anyone
> > > > > else out as well.
> > > > > 
> > > > > 
> > > > > http://polish.slavic.pitt.edu/~swan/theta/Phobos.xmind
> > > > 
> > > > may be you could expose/share your work via service like
> > > > http://www.xmind.net/share/
> > > > because not everybody have installed xmind...
> > > 
> > > Good point.  I'll do that on Monday when I'm back at the office.  I
> > > updated std.datetime to 2.052 yesterday (didn't realize there was a
> > > new version until then).
> > 
> > LOL. Yeah. It's practically not even related to the previous version. The
> > few items that it had were moved to core.time and left in std.datetime,
> > but it's very small in comparison to what was added. What's there _is_
> > thoroughly documented though. So, depending on what your problem is with
> > Phobos' documentation is (I don't know what your problem with it is),
> > maybe you'll like that better. If your problem with the documentation
> > has to do with the fact that the links on the top aren't organized
> > (which they obviously need to be), then that problem still needs to be
> > dealt with. There has been _some_ work in that direction though. Andrei
> > has been working to improve how std.algorithm's links are laid out, and
> > there has been a person or two who have been working on ways to improve
> > the way all that is laid out in general, but it hasn't yet reached the
> > point that Phobos' basic documentation layout has been truly fixed.
> > Still, it's good to have as much documentation as we do, even if it
> > could use some improvements as far as layout goes.
> > - Jonathan M Davis
> 
> Yeah, it was amazing when I opened up the new datetime source file.  The
> previous one just had Ticks and StopWatch along with 3 public functions
> outside of those. It took me a while to go through the new one.
> 
> 
> My problem with the documentation isn't that it lacks information.  Most of
> the developers have done an excellent job in that regards.  The problem is
> the layout. It takes as much time to find the information on the webpage
> as it does to just search through the source code.  And both can be fairly
> crazy to look through.  I believe that if you have to hit ctrl-f to find
> what you need then there's a fundamental flaw with the layout.

Well, I don't think that the documentation layout needs improvement, but work on 
that has been a low enough priority that progress has been slow.

> Not everyone thinks alike, though.  I just wanted to offer an alternative. 
> Since no IDEs offer intellisense (VisualD's is rudimentary but improving)
> there's a severe need for quick referencing.  I was hoping to achieve that
> with XMind.

Well, I'd never heard of XMind before you mentioned it, so I have no idea what 
it offers, but if it can give a better version of the documentation, then it may 
be worth looking at.

- Jonathan M Davis