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 <[email protected]> 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 [email protected]. > 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 [email protected]. 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.
