How to prepare and present new pict3d internal documentation?
27 views
Skip to first unread message
Hendrik Boom
Dec 31, 2019, 7:30:32 AM12/31/19
to Racket Users
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
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
Jay McCarthy
Jan 1, 2020, 12:42:24 PM1/1/20
to Racket Users
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.
> --
> 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...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/20191231123027.lcspvrc6nc5sdlgr%40topoi.pooq.com.
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.
> 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...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/20191231123027.lcspvrc6nc5sdlgr%40topoi.pooq.com.
Reply all
Reply to author
Forward
0 new messages