How to prepare and present new pict3d internal documentation? I'm busy working on new internal documentation of pict3d. I'd like some advice on how to prepare and present the resulting document (which isn't even a draft yet).
Pict3D's various components look to be useful on their own, and I'd like to use texture mapping with it. This requires some level of understanding of it internals. At present there seems to be no such internal documentation. (or is there an ancient thesis or lost internal project report or some thing like that? If so I haven't foud it.) What I have now is a file of ragged notes on pict3d. It constitutes a kind of diary of my questions and discoveries as I work my way into it, a few hours at a time every week or two. you can see it on github: https://github.com/hendrikboom3/rackettown/blob/master/notes.pict3d If you bother to look at them it's obvious that they won't constitute the internal documentation I' looking for. Before I actually start producing definitive documentation, I'd like to have a few answers. In what form should I present the internal API? Of course, a scribble document, and there are conventions for that. (1) Should it be a separate document from the existing pict3d user documentation? (2) Should it be part of the source code for pict3d? (which would presumably result in a pull request someday) That might well make the pict3d source code itself somewhat more comprehensible, at least while I'm trying to read it. But I'd need a mechanism to extract comments and other information from the source code and assemble it into a readable document. Or should it be a separate file within the pict3d source code? Or should it have its own source repository? (3) Are there any established conventions for API documentation in Racket source code? (3a) I've found there is no shortage of hard-to-use API documentations generated automatically from source code. But it's possible to do better. The Trestle Reference Manual ( http://www.opencm3.net/doc/src_reports/src-068.pdf ) is an example of it done right. I'd like to do it right myself. This is an open project. Advice, critique, proposed content, and useful information are all welcome. Especially answers to relevant questions I haven't thought of yet! -- hendrik -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/20191231123027.lcspvrc6nc5sdlgr%40topoi.pooq.com.
