Commit 02b22ea4 authored by Gary King's avatar Gary King
Browse files

Documentation improvements

* added docstring to the method-combination
  standard-asdf-method-combination

* added docstring to the generic-function traverse

* added description of `test-op` to the manual

* removed descriptions of test-system-version operation and
  feature-dependent-op
parent 90abd538
Loading
Loading
Loading
Loading
+15 −1
Original line number Diff line number Diff line
@@ -165,6 +165,14 @@
(defparameter +asdf-methods+
  '(perform explain output-files operation-done-p))

(setf (documentation 'standard-asdf-method-combination 
		     'method-combination)
      "This method combination is based on the standard method combination,
but defines a new method-qualifier, `asdf:around`.  `asdf:around`
methods will be run *around* any `:around` methods, so that the core
protocol may employ around methods and those around methods will not
be overridden by around methods added by a system developer.")

(define-method-combination standard-asdf-method-combination ()
  ((around-asdf (around))
   (around (:around))
@@ -260,7 +268,13 @@ the head of the tree"))

(defgeneric component-self-dependencies (operation component))

(defgeneric traverse (operation component))
(defgeneric traverse (operation component)
  (:documentation 
"Generate and return a plan for performing `operation` on `component`.

The plan returned is a list of dotted-pairs. Each pair is the `cons`
of ASDF operation object and a `component` object. The pairs will be 
processed in order by `operate`."))


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+13 −16
Original line number Diff line number Diff line
@@ -432,26 +432,23 @@ that.
If you are creating a component type, you need to implement
this operation - at least, where meaningful.

-- Operation: **test-system-version** &key minimum  
-- Operation: **test-op**

This operation should test the specified component. ASDF does
not (currently) provide a method for returning a value from
the test-op (or any other operation), so the implementor must
ensure that executing `test-op` has the side effect
of printing useful information about the tests to the CL
stream `*standard-output*`.

Asks the system whether it satisfies a version requirement.
The default method for `test-op` does nothing, and will have
to be overridden, but invoking `test-op` on a component for
which nothing is defined will be a simple no-op.

The default method accepts a string, which is expected to
contain of a number of integers separated by #\. characters.
The method is not recursive. The component satisfies the
version dependency if it has the same major number as
required and each of its sub-versions is greater than or
equal to the sub-version number required.
The default dependency for `test-op` on a system is to
require `load-op` on that system.

-- Operation: **feature-dependent-op**  

An instance of `feature-dependent-op` will ignore any
components which have a `features` attribute, unless the
feature combination it designates is satisfied by
`*features*`. This operation is not intended to be
instantiated directly, but other operations may inherit from
it.
The default method for `operation-done-p` for `test-op` is to return `nil` regardless of component because tests should usually be run whether or not they have been run previously.


####  Creating new operations