Skip to content
Snippets Groups Projects
Commit f6e2390c authored by Francois-Rene Rideau's avatar Francois-Rene Rideau
Browse files

Second pass on docstrings previously edited by rpgoldman.

Also fix the name of the :initarg for upward-operation (oops).
parent 78fe4a70
No related branches found
No related tags found
No related merge requests found
...@@ -124,64 +124,66 @@ You can put together sentences using this phrase.")) ...@@ -124,64 +124,66 @@ You can put together sentences using this phrase."))
(cdr (assoc (type-of o) (component-in-order-to c))))) ; User-specified in-order dependencies (cdr (assoc (type-of o) (component-in-order-to c))))) ; User-specified in-order dependencies
;;;; upward-operation, downward-operation ;;;; upward-operation, downward-operation, sideway-operation, selfward-operation
;; These together handle actions that propagate along the component hierarchy. ;; These together handle actions that propagate along the component hierarchy or operation universe.
;; Downward operations like load-op or compile-op propagate down the hierarchy:
;; 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 () (with-upgradability ()
(deftype op-class-designator () (deftype operation-class-designator ()
'(or symbol class)) '(or symbol class))
(defclass downward-operation (operation) (defclass downward-operation (operation)
((downward-operation ((downward-operation
:initform nil :initarg :downward-operation :reader downward-operation :initform nil :initarg :downward-operation :reader downward-operation
:type op-class-designator :allocation :class)) :type operation-class-designator :allocation :class))
(:documentation "A DOWNWARD-OPERATION object propagates its DOWNWARD-OPERATION value to its children. (:documentation "A DOWNWARD-OPERATION's dependencies propagate down the component hierarchy.
I.e., if DOWNWARD-OPERATION OP is requested on C, \(DOWNWARD-OPERATION OP\) will be propagated to C's I.e., if O is a DOWNWARD-OPERATION and its DOWNWARD-OPERATION slot designates operation D, then
children. E.g., in order to load a MODULE, you must load all of the children of the MODULE. the action (O . M) of O on module M will depends on each of (D . C) for each child C of module M.
\(DOWNWARD-OPERATION OP\) defaults to be the same as OP's class.")) The default value for slot DOWNWARD-OPERATION is NIL, which designates the operation O itself.
E.g. in order for a MODULE to be loaded with LOAD-OP (resp. compiled with COMPILE-OP), all the
children of the MODULE must have been loaded with LOAD-OP (resp. compiled with COMPILE-OP."))
(defmethod component-depends-on ((o downward-operation) (c parent-component)) (defmethod component-depends-on ((o downward-operation) (c parent-component))
`((,(or (downward-operation o) o) ,@(component-children c)) ,@(call-next-method))) `((,(or (downward-operation o) o) ,@(component-children c)) ,@(call-next-method)))
;; Upward operations like prepare-op propagate up the component hierarchy:
;; operation on a child depends-on operation on its parent.
;; By default, an operation propagates itself, but it may propagate another one instead.
(defclass upward-operation (operation) (defclass upward-operation (operation)
((upward-operation ((upward-operation
:initform nil :initarg :downward-operation :reader upward-operation :allocation :class)) :initform nil :initarg :upward-operation :reader upward-operation
(:documentation "An UPWARD-OPERATION object propagates its UPWARD-OPERATION value to its parent. :type operation-class-designator :allocation :class))
I.e., if UPWARD-OPERATION OP is requested on C, \(UPWARD-OPERATION OP\) will be propagated to C's (:documentation "An UPWARD-OPERATION has dependencies that propagate up the component hierarchy.
parent. E.g., in order to PREPARE-OP (prepare to load) a file C, ASDF must perform PREPARE-OP I.e., if O is an instance of UPWARD-OPERATION, and its UPWARD-OPERATION slot designates operation U,
on C's parent MODULE or SYSTEM. then the action (O . C) of O on a component C that has the parent P will depends on (U . P).
\(UPWARD-OPERATION OP\) defaults to be the same as OP's class.")) The default value for slot UPWARD-OPERATION is NIL, which designates the operation O itself.
E.g. in order for a COMPONENT to be prepared for loading or compiling with PREPARE-OP, its PARENT
must first be prepared for loading or compiling with PREPARE-OP."))
;; For backward-compatibility reasons, a system inherits from module and is a child-component ;; For backward-compatibility reasons, a system inherits from module and is a child-component
;; so we must guard against this case. ASDF4: remove that. ;; so we must guard against this case. ASDF4: remove that.
(defmethod component-depends-on ((o upward-operation) (c child-component)) (defmethod component-depends-on ((o upward-operation) (c child-component))
`(,@(if-let (p (component-parent c)) `(,@(if-let (p (component-parent c))
`((,(or (upward-operation o) o) ,p))) ,@(call-next-method))) `((,(or (upward-operation o) o) ,p))) ,@(call-next-method)))
;; Sibling operations propagate to siblings in the component hierarchy:
;; operation on a child depends-on operation on its parent.
;; By default, an operation propagates itself, but it may propagate another one instead.
(defclass sideway-operation (operation) (defclass sideway-operation (operation)
((sideway-operation ((sideway-operation
:initform nil :initarg :sideway-operation :reader sideway-operation :allocation :class)) :initform nil :initarg :sideway-operation :reader sideway-operation
(:documentation "A SIDEWAY-OPERATION object propagates its SIDEWAY-OPERATION value to its \"leftward\" :type operation-class-designator :allocation :class))
siblings: those components that have the same parent as the object component, C, and that are ordered prior to (:documentation "A SIDEWAY-OPERATION has dependencies that propagate \"sideway\" to siblings
C in the :DEPENDS-ON graph of C's parent. that a component depends on. I.e. if O is a SIDEWAY-OPERATION, and its SIDEWAY-OPERATION slot
\(SIDEWAY-OPERATION OP\) defaults to be the same as OP's class.")) designates operation S (where NIL designates O itself), then the action (O . C) of O on component C
depends on each of (S . D) where D is a declared dependency of C.
E.g. in order for a COMPONENT to be prepared for loading or compiling with PREPARE-OP,
each of its declared dependencies must first be loaded as by LOAD-OP."))
(defmethod component-depends-on ((o sideway-operation) (c component)) (defmethod component-depends-on ((o sideway-operation) (c component))
`((,(or (sideway-operation o) o) `((,(or (sideway-operation o) o)
,@(loop :for dep :in (component-sideway-dependencies c) ,@(loop :for dep :in (component-sideway-dependencies c)
:collect (resolve-dependency-spec c dep))) :collect (resolve-dependency-spec c dep)))
,@(call-next-method))) ,@(call-next-method)))
;; Selfward operations propagate to themselves a sub-operation:
;; they depend on some other operation being acted on the same component.
(defclass selfward-operation (operation) (defclass selfward-operation (operation)
((selfward-operation ((selfward-operation
;; no :initform -- if you are going to propagate an operation to yourself, you must :initarg :selfward-operation ;; NB: no :initform -- if an operation depends on another one,
;; specify it explicitly. ;; which that is must explicitly specified.
:initarg :selfward-operation :reader selfward-operation :allocation :class)) :type operation-class-designator :reader selfward-operation :allocation :class))
(:documentation "A SELFWARD-OPERATION object propagates its SELFWARD-OPERATION value to itself. (:documentation "A SELFWARD-OPERATION depends on another operation on the same component.
I.e., if SELFWARD-OPERATION OP is requested on C, \(SELFWARD-OPERATION OP\) will first be performed on C.")) I.e., if O is a SELFWARD-OPERATION, and its SELFWARD-OPERATION designates operation S, then
the action (O . C) of O on component C depends on (S . C).
E.g. before a component may be loaded by LOAD-OP, it must have been compiled by COMPILE-OP."))
(defmethod component-depends-on ((o selfward-operation) (c component)) (defmethod component-depends-on ((o selfward-operation) (c component))
`(,@(loop :for op :in (ensure-list (selfward-operation o)) `(,@(loop :for op :in (ensure-list (selfward-operation o))
:collect `(,op ,c)) :collect `(,op ,c))
......
...@@ -50,7 +50,7 @@ ...@@ -50,7 +50,7 @@
(defun package-dependencies (defpackage-form) (defun package-dependencies (defpackage-form)
"Return a list of packages depended on by the package "Return a list of packages depended on by the package
defined in DEFPACKAGE-FORM. A package is depended upon if defined in DEFPACKAGE-FORM. A package is depended upon if
the DEFPACKAGE-FORM imports a symbol from it." the DEFPACKAGE-FORM uses it or imports a symbol from it."
(assert (defpackage-form-p defpackage-form)) (assert (defpackage-form-p defpackage-form))
(remove-duplicates (remove-duplicates
(while-collecting (dep) (while-collecting (dep)
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment