Define documentation style #51

pastor commented 2025年06月11日 21:29:17 +02:00

Before tackling the documentation issue, I think we should agree on how to do it.

One think I definitely want is that all files should have a header in the style of elisp packages. I propose the following structure for the header:

;;; <file-name>.scm --- <synopsis>
;; <copyright assignments>
;; <license>
;;; Commentary:
;; <purpose of the file>.
;;; Code:

Before tackling the [documentation issue](https://codeberg.org/lapislazuli/blue/issues/31), I think we should agree on how to do it. One think I definitely want is that **all** files should have a header in the style of elisp packages. I propose the following structure for the header: ``` ;;; <file-name>.scm --- <synopsis> ;; <copyright assignments> ;; <license> ;;; Commentary: ;; <purpose of the file>. ;;; Code: ```

old commented 2025年06月11日 22:02:04 +02:00

I would ike to keep the license at the top of the file followed by copyrights then synopsis and commentary and code.

Licenses need to be the closest possible to top of the file (when possible) because tools that detect them are expecting to find them in the first lines.

So:

;;; SPDX-License-Identifier: LGPL-3.0-or-later
;;; SPDX-FileCopyrightText: 2025 Olivier Dion <olivier-dion@proton.me>
;;;
;;; blue/cache.scm --- File-system caching of objects.
;;;
;;; Commentary:
;;;
;;; Whenever an object needs to used from different invocations (processes) of
;;; `blue', then the cache can be used to store that object on the file-system
;;; and load it back later.
;;;
;;; Code:
(define-module (blue cache)
 #:use-module (blue file-system directory)
 #:use-module (blue serialize)
 #:use-module (blue states)
 #:use-module (ice-9 exceptions)
 #:export (cache-ref
 cache-link!
 cache-set!
 make-cache))
(define (make-cache directory)
 (mkdir-p directory)
 (call-with-output-file (format #f "~a/.lock" directory)
 (lambda (lock)
 #f))
 directory)
(define (cache-file-path cache hash)
 (format #f "~a/~a"
 cache (number->string
 (logand hash (1- (ash 1 256)))
 16)))
;;; Is this lock really necessary?
(define (cache-lock cache)
 (format #f "~a/.lock" cache))
(define (with-cache-lock shared-or-exclusive cache thunk)
 (call-with-input-file (cache-lock cache)
 (lambda (lock)
 (dynamic-wind
 (lambda ()
 (flock lock shared-or-exclusive))
 thunk
 (lambda ()
 (flock lock LOCK_UN))))))
(define (with-read-cache-lock cache thunk)
 (with-cache-lock LOCK_SH cache thunk))
(define (with-write-cache-lock cache thunk)
 (with-cache-lock LOCK_EX cache thunk))
(define* (cache-ref hash
 #:optional (cache (current-cache)))
 (with-read-cache-lock cache
 (lambda ()
 (let ((path (cache-file-path cache hash)))
 (if (file-exists? path)
 (call-with-input-file path
 (lambda (port)
 (eval (read port) (current-module))))
 #f)))))
(define* (cache-set! hash value
 #:optional (cache (current-cache)))
 (with-write-cache-lock cache
 (lambda ()
 (call-with-output-file (cache-file-path cache hash)
 (lambda (port)
 (serialize value port))))))
(define* (cache-link! link-hash other-hash
 #:optional (cache (current-cache)))
 (let ((target (cache-file-path cache other-hash))
 (link (cache-file-path cache link-hash)))
 (with-write-cache-lock cache
 (lambda ()
 (if (file-exists? target)
 (begin
 (when (file-exists? link)
 (delete-file link))
 (symlink (basename target) link))
 (raise-exception
 (make-exception
 (make-external-error)
 (make-exception-with-origin link)
 (make-exception-with-irritants target)
 (make-exception-with-message
 "Target to link does not exist in the cache."))))))))

I would ike to keep the license at the top of the file followed by copyrights then synopsis and commentary and code. Licenses need to be the closest possible to top of the file (when possible) because tools that detect them are expecting to find them in the first lines. So: ```scheme ;;; SPDX-License-Identifier: LGPL-3.0-or-later ;;; SPDX-FileCopyrightText: 2025 Olivier Dion <olivier-dion@proton.me> ;;; ;;; blue/cache.scm --- File-system caching of objects. ;;; ;;; Commentary: ;;; ;;; Whenever an object needs to used from different invocations (processes) of ;;; `blue', then the cache can be used to store that object on the file-system ;;; and load it back later. ;;; ;;; Code: (define-module (blue cache) #:use-module (blue file-system directory) #:use-module (blue serialize) #:use-module (blue states) #:use-module (ice-9 exceptions) #:export (cache-ref cache-link! cache-set! make-cache)) (define (make-cache directory) (mkdir-p directory) (call-with-output-file (format #f "~a/.lock" directory) (lambda (lock) #f)) directory) (define (cache-file-path cache hash) (format #f "~a/~a" cache (number->string (logand hash (1- (ash 1 256))) 16))) ;;; Is this lock really necessary? (define (cache-lock cache) (format #f "~a/.lock" cache)) (define (with-cache-lock shared-or-exclusive cache thunk) (call-with-input-file (cache-lock cache) (lambda (lock) (dynamic-wind (lambda () (flock lock shared-or-exclusive)) thunk (lambda () (flock lock LOCK_UN)))))) (define (with-read-cache-lock cache thunk) (with-cache-lock LOCK_SH cache thunk)) (define (with-write-cache-lock cache thunk) (with-cache-lock LOCK_EX cache thunk)) (define* (cache-ref hash #:optional (cache (current-cache))) (with-read-cache-lock cache (lambda () (let ((path (cache-file-path cache hash))) (if (file-exists? path) (call-with-input-file path (lambda (port) (eval (read port) (current-module)))) #f))))) (define* (cache-set! hash value #:optional (cache (current-cache))) (with-write-cache-lock cache (lambda () (call-with-output-file (cache-file-path cache hash) (lambda (port) (serialize value port)))))) (define* (cache-link! link-hash other-hash #:optional (cache (current-cache))) (let ((target (cache-file-path cache other-hash)) (link (cache-file-path cache link-hash))) (with-write-cache-lock cache (lambda () (if (file-exists? target) (begin (when (file-exists? link) (delete-file link)) (symlink (basename target) link)) (raise-exception (make-exception (make-external-error) (make-exception-with-origin link) (make-exception-with-irritants target) (make-exception-with-message "Target to link does not exist in the cache.")))))))) ```

pastor commented 2025年06月11日 23:58:33 +02:00

Okay! I've configured auto-insert mode in the project's dir-local variables so you can do M-x auto-insert to insert this template a header comment of any scheme file. If auto-insert-mode is on the user will be prompted to inject this template for new scheme files.

The changes are in #52.

Okay! I've configured auto-insert mode in the project's dir-local variables so you can do `M-x auto-insert` to insert this template a header comment of any scheme file. If `auto-insert-mode` is on the user will be prompted to inject this template for new scheme files. The changes are in #52.

old commented 2025年08月03日 17:33:47 +02:00

Add a section in the BLUE info manual under the Contributing explaining this issue.

Add a section in the BLUE info manual under the *Contributing* explaining this issue.

pastor commented 2026年05月08日 10:30:46 +02:00

We should probably use this issue to discuss how we are going to generate some parts of the documentation from the sources.

Currently we are playing with a way to extract documentation from sources here.

We should probably use this issue to discuss how we are going to generate some parts of the documentation from the sources. Currently we are playing with a way to extract documentation from sources [here](https://codeberg.org/lapislazuli/blue/src/user-manual/blue/stencils/guile-texinfo.scm).

lapislazuli/blue