>>> 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!
