Improve docstring handling #30

pkulev · 2026-09-18T17:47:03+02:00

pkulev commented

2026-09-18 17:47:03 +02:00

Summary

Closes #5: a leading string on fn / struct / union / enum is a docstring, lifted by semen into a comment form so the writer prints it above the C declaration rather than inside the body.
pub function docstrings survive --public-interface and imports (the prototype keeps the string; the importer's semen pass emits the comment).
sex-fn-* accessors now follow current (fn name args ret …) syntax, including extern fn.

A string later in a function body is left as a statement. var and define are unchanged: a string there is already an initializer or #define value (; comments still work above them).

Comments are /* … */, same as ; comments, not the // from the original ticket.

(fn greet ((name (* char))) void
  "Greet the thing using NAME."
  (printf "Hello %s!\n" name))

(struct point
  "A 2D point."
  ((x y int)))

/* Greet the thing using NAME. */
static void greet (char * name) {
           printf("Hello %s!\n", name);
       }

/* A 2D point. */
struct point {
    int x, y;
};

A docstring-only fn stays a prototype.

Test plan

make check
sexc file.sex -C --line-directives=none on a function with a one-line docstring: comment sits above the declaration, not in the body
multiline docstring keeps both paragraphs
(fn helper ((a int)) int "Forward.") still emits a prototype
docstring after struct / enum / union name
sexc tests/modules/greet.sex --public-interface still shows the greet docstring on the prototype

## Summary - Closes https://git.kotobank.ch/alex-eg/sex/issues/5: a leading string on `fn` / `struct` / `union` / `enum` is a docstring, lifted by semen into a comment form so the writer prints it **above** the C declaration rather than inside the body. - `pub` function docstrings survive `--public-interface` and imports (the prototype keeps the string; the importer's semen pass emits the comment). - `sex-fn-*` accessors now follow current `(fn name args ret …)` syntax, including `extern fn`. A string later in a function body is left as a statement. `var` and `define` are unchanged: a string there is already an initializer or `#define` value (`;` comments still work above them). Comments are `/* … */`, same as `;` comments, not the `//` from the original ticket. ```scheme (fn greet ((name (* char))) void "Greet the thing using NAME." (printf "Hello %s!\n" name)) (struct point "A 2D point." ((x y int))) ``` ```c /* Greet the thing using NAME. */ static void greet (char * name) { printf("Hello %s!\n", name); } /* A 2D point. */ struct point { int x, y; }; ``` A docstring-only `fn` stays a prototype. ## Test plan - [x] `make check` - [x] `sexc file.sex -C --line-directives=none` on a function with a one-line docstring: comment sits above the declaration, not in the body - [x] multiline docstring keeps both paragraphs - [x] `(fn helper ((a int)) int "Forward.")` still emits a prototype - [x] docstring after `struct` / `enum` / `union` name - [x] `sexc tests/modules/greet.sex --public-interface` still shows the greet docstring on the prototype

pkulev added the feature label 2026-09-18 17:47:03 +02:00

pkulev added 1 commit 2026-09-18 17:47:03 +02:00

TMP

Sex CI / build-linux (pull_request) Successful in 4m45s

Details

78862cfe4f

pkulev requested review from alex-eg 2026-09-18 17:47:03 +02:00

alex-eg commented

2026-09-19 00:58:23 +02:00

🤯

pkulev force-pushed feature/docstrings from 78862cfe4f to 434086ade8

2026-09-21 23:51:39 +02:00

Compare

pkulev changed title from ~~WIP: Improve docstring handling~~ to Improve docstring handling

2026-09-21 23:52:03 +02:00

alex-eg approved these changes 2026-09-22 18:59:01 +02:00

alex-eg left a comment

🔥

Looks very good! Thanks!

🔥 Looks very good! Thanks!

pkulev merged commit 434086ade8 into main

2026-09-22 22:33:17 +02:00

pkulev deleted branch feature/docstrings

2026-09-22 22:33:17 +02:00

pkulev referenced this pull request

2026-09-22 22:43:42 +02:00

Implement docstrings for fn definitions #5

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: alex-eg/sex#30

Allow edits from maintainers