1. Do we foresee using srcdoc for new work in the future, and is it suitable as part of a backend for other in-source documentation?

2. What do people think of writing reusable modules approximately like the example below?  Is that something you'd want to do?

(The basic idea is that you usually have one source file per module, which is self-contained, with polished and up-to-date documentation and unit tests and such, and is generally written and maintained as if it is reused or could be reused as its own package at any time. All this, in a fairly "lightweight" form, although we acknowledge that the below example is a big bureucratic load for two one-line procedures, but maybe it is practical for most real-world modules.)

(For this example, I used capitalized names, to avoid confusing with familiar names, but some other names that weren't capitalized might also work.  Note that some forms are dual-purpose; for example, `Proc` turns into something like a Scribble `defproc` and a Racket code `define`, `provide`, and a contract somewhere.  Note that I'm intentionally putting `KnownIssues` and `History` into the source file, in a lightweight and self-contained kind of way, but those forms could be optional, for people/projects that prefer to use separate issue-tracking and release notes.  Also note that, if `Package` weren't present here, you could imagine this module being part of a multi-module package, including documentation that is incorporated by reference into a bigger document, but, by default, we want to encourage lightweight reusable modules.}

---- BEGIN ----

#lang turbo-racket

@Package[
    @Name{foo}
    @Version{1.1}
    @Web{http://www.example.com/foo/}
    @Authors{Jane Doe}
    @Legal{Copyright 2025 Jane Doe. You may blah blah blah
           blah blah blah.}]

(Require (bunny :version "1.2+")
         (puppy :url "https://git.example.com/release/2.0/puppy.rkt";
                :sha256 "347ab429830..."))

@Section{Introduction}

@Doc{This package provides a @racket{foo} and @racket{bar},
     for all your fooing and anti-fooing needs.}

@Doc{For example, you could do:

     ...

     and it would totally work, dude.}

@Section{Main Interface}

@Doc{The interface is just two procedures.}

(Proc (foo (x real?) (y real))
             real?
  @Doc{This returns a foo of @var{x} and @var{y}.
       It's really quite neat.}
  (* x y x y x y))

(Tests (test (foo 1 2) 666)
       (test (foo 3 4) 42))

(Proc (bar (x real?) (y real))
             real?
  @Doc{We don't know why anyone would want to do this,
       but the customer is always right.}
  (+ x y x y x y))

(Tests (test (bar 0 0) 0)
       (test (bar 1999 1999) 0))

@Section{Conveniences}

...

@Section{Quantum Theory}

@Doc{Perhaps a discussion is in order.

     ...}

@KnownIssues[

    @item{Not everyone yet fooifies.}

    @item{Fix intermittent explosions.}]}

@History[

    @Release["1.1" "2025-12-25"]{
        @itemize[
            @item{Reversed behavior of @racket{foo} and @racket{bar}.}
            @item{Documented explosion issue.}]}

    @Release["1.0" "2025-12-24"]{
        This was a good initial release.  We got out there,
        and gave 110%.}]}

---- END ----

--
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.
For more options, visit https://groups.google.com/d/optout.

Reply via email to