Of course, this is not makes class/method comments less important. But i vote for online documentation first.
Online documents are mainly for, let's say, lazy users of your system, currently we're still in core development, so I would go for the things needed by programmers. That is Examples, Class Comments and maybe method comments.
the problem is that many parts of it needs illustrations. it is better to see once, than hear many times.
for instance, tell me if you can understand this:
path can have many contours, a new contour start either from 'close' command or 'moveto' command which implicitly closes the current contour (for fills, but not for strokes).
using multiple contours in path, you can create hollow shapes by defining intersecting shapes (per contour) with different winding (clockwise /counterclockwise).
if I have an example I can run with the vey same text you wrote I understand everything! And I think with something like Esteban's athen workspace that should be fairly easy to achieve. basic contour examples ====================== - path with 1 contour - path with 2 contours - some fancy example with complex contours Hollow shapes ============= - start with a rect - start with a rect with another rect cut out => I have running code I can copy paste, that is worth more than some text I have to transform into a running model in my head... => no graphs needed, all your visualizations are running code examples!