From 9a338e766a6593e6f75dc9c930a4464740181261 Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@gmail.com> Date: Mon, 6 Jan 2014 23:04:05 -0600 Subject: [PATCH] Document strings for the OPERATION subclasses that handle propagation. --- action.lisp | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/action.lisp b/action.lisp index 8df6719b..ab7c1832 100644 --- a/action.lisp +++ b/action.lisp @@ -130,9 +130,16 @@ You can put together sentences using this phrase.")) ;; operation on a parent depends-on operation on its children. ;; By default, an operation propagates itself, but it may propagate another one instead. (with-upgradability () + (deftype op-class-designator () + '(or symbol class)) (defclass downward-operation (operation) ((downward-operation - :initform nil :initarg :downward-operation :reader downward-operation :allocation :class))) + :initform nil :initarg :downward-operation :reader downward-operation + :type op-class-designator :allocation :class)) + (:documentation "A DOWNWARD-OPERATION object propagates its DOWNWARD-OPERATION value to its children. +I.e., if DOWNWARD-OPERATION OP is requested on C, \(DOWNWARD-OPERATION OP\) will be propagated to C's +children. E.g., in order to load a MODULE, you must load all of the children of the MODULE. +\(DOWNWARD-OPERATION OP\) defaults to be the same as OP's class.")) (defmethod component-depends-on ((o downward-operation) (c parent-component)) `((,(or (downward-operation o) o) ,@(component-children c)) ,@(call-next-method))) ;; Upward operations like prepare-op propagate up the component hierarchy: @@ -140,7 +147,12 @@ You can put together sentences using this phrase.")) ;; By default, an operation propagates itself, but it may propagate another one instead. (defclass upward-operation (operation) ((upward-operation - :initform nil :initarg :downward-operation :reader upward-operation :allocation :class))) + :initform nil :initarg :downward-operation :reader upward-operation :allocation :class)) + (:documentation "An UPWARD-OPERATION object propagates its UPWARD-OPERATION value to its parent. +I.e., if UPWARD-OPERATION OP is requested on C, \(UPWARD-OPERATION OP\) will be propagated to C's +parent. E.g., in order to PREPARE-OP (prepare to load) a file C, ASDF must perform PREPARE-OP +on C's parent MODULE or SYSTEM. +\(UPWARD-OPERATION OP\) defaults to be the same as OP's class.")) ;; For backward-compatibility reasons, a system inherits from module and is a child-component ;; so we must guard against this case. ASDF4: remove that. (defmethod component-depends-on ((o upward-operation) (c child-component)) @@ -151,7 +163,11 @@ You can put together sentences using this phrase.")) ;; By default, an operation propagates itself, but it may propagate another one instead. (defclass sideway-operation (operation) ((sideway-operation - :initform nil :initarg :sideway-operation :reader sideway-operation :allocation :class))) + :initform nil :initarg :sideway-operation :reader sideway-operation :allocation :class)) + (:documentation "A SIDEWAY-OPERATION object propagates its SIDEWAY-OPERATION value to its \"leftward\" +siblings: those components that have the same parent as the object component, C, and that are ordered prior to +C in the :DEPENDS-ON graph of C's parent. +\(SIDEWAY-OPERATION OP\) defaults to be the same as OP's class.")) (defmethod component-depends-on ((o sideway-operation) (c component)) `((,(or (sideway-operation o) o) ,@(loop :for dep :in (component-sideway-dependencies c) @@ -161,7 +177,11 @@ You can put together sentences using this phrase.")) ;; they depend on some other operation being acted on the same component. (defclass selfward-operation (operation) ((selfward-operation - :initform nil :initarg :selfward-operation :reader selfward-operation :allocation :class))) + ;; no :initform -- if you are going to propagate an operation to yourself, you must + ;; specify it explicitly. + :initarg :selfward-operation :reader selfward-operation :allocation :class)) + (:documentation "A SELFWARD-OPERATION object propagates its SELFWARD-OPERATION value to itself. +I.e., if SELFWARD-OPERATION OP is requested on C, \(SELFWARD-OPERATION OP\) will first be performed on C.")) (defmethod component-depends-on ((o selfward-operation) (c component)) `(,@(loop :for op :in (ensure-list (selfward-operation o)) :collect `(,op ,c)) -- GitLab