I don't think there is precedent in Racket for stuff like this. There are quite a few programs that have really long comments at their start that explain how they work and for the Web server, there's a separate section of the docs that have a bunch of random sub-pieces documented --- https://docs.racket-lang.org/web-server-internal/private.html --- I think if I were doing this today, I would have made a bunch of little packages. It would not surprise me if parts of pict3d could be other packages and/or independently useful and it would make sense to document them that way.
Jay -- Jay McCarthy Associate Professor @ CS @ UMass Lowell http://jeapostrophe.github.io Vincit qui se vincit. On Tue, Dec 31, 2019 at 7:30 AM Hendrik Boom <hend...@topoi.pooq.com> wrote: > > 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. -- 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/CAJYbDak%2BQr%3DGc4CAqepb4rfJ0DF7eHPhWKtvZRWzRq1%2B_0-WEg%40mail.gmail.com.