devops: Document bindings in (devops).

diff --git a/src/devops/build.texi b/src/devops/build.texi
index 291c4cbc0cfb0533279af208fced61a2eae4fd12..fb5c2a0026c7acef00eaeea3c25df8eb628c50b4 100644 (file)
--- a/src/devops/build.texi
+++ b/src/devops/build.texi
@@ -67,8 +67,7 @@ git pull puck pucked
 The devops build system is configured by a @file{config.scm} file in
 its build area, @file{devops/} (possibly a symbolic link).  The
 @file{devops/config.scm} file is loaded into the @code{(devops)}
-package where it can find procedures to set build system variables and
-customize any part of the build processes.
+package where it can find procedures to set build system variables.
 
 @deffn Procedure project-name [name]
 Returns the project name (a string) after setting it to @var{name}
@@ -77,6 +76,7 @@ whitespace or punctuation; it is used to create file names.  Until it
 is set the project name is @code{"new-scheme"}.
 @end deffn
 
+@anchor{plugin}
 @deffn Procedure plugin name directory
 Adds a plugin to the project.  @var{Name} should be a string.  It will
 be concatenated with the project name and a hyphen to create package
@@ -262,7 +262,60 @@ project web site.  @uref{http://birchwood-abbey.net/~puck/Scheme/}
 
 All of the devops release procedures warn of ``lint'' in the source
 code and documentation.  At the moment, only out-of-date version
-numbers are detected.
+numbers are detected.  Eventually a few more standard constraints
+might be checked, but lint detection is a matter of rather
+idiosyncratic project policy.  Most lint detection is expected to
+happen in the lint hooks.
+
+@deffn Procedure core-lint-hook version changes dirt
+If true, the value of this binding is applied to three arguments.
+@enumerate
+@item
+@var{version}---A string like @code{"9.2.7"}.
+@item
+@var{changes}---A list of strings, the paths (relative to the root of
+the git working directory tree) to files that have changed since the
+last release.
+@item
+@var{dirt}---A list of strings, the paths (relative) to the ``dirty''
+files, files with uncommitted changes.
+@end enumerate
+The value of the hook should be a list of strings, messages for the
+luser.
+@end deffn
+
+@deffn Procedure plugin-lint-hook plugin version changes dirt
+Like @code{core-lint-hook} but takes an additional argument:
+@var{plugin}---an object created by the @code{plugin} procedure.
+@end deffn
+
+A few procedures are made available in the @code{(devops)} package to
+aid in the definition of procedures that check for project policy
+violations.
+
+A couple procedures can be applied to the plugin objects passed as
+arguments to the @code{plugin-lint-hook}.  They access the name and
+directory provided to the @code{plugin} procedure when the object was
+created.  @xref{plugin}.
+
+@deffn Procedure plugin-name plugin
+Returns the string naming the @var{plugin} object.
+@end deffn
+
+@deffn Procedure plugin-directory plugin
+Returns the string naming the subdirectory of the git repository, the
+root of @var{plugin}'s source tree.
+@end deffn
+
+There is just one procedure for checking policy.
+
+@deffn Procedure plugin-deffn-lint plugin pkg exceptions
+If @var{plugin}'s source contains a @file{.texi} file with the same
+name, check that it has a Texinfo @code{@@deffn} for each binding
+exported to the global package and the @var{pkg} package (if @var{pkg}
+is not false).  @var{Exceptions} should be a list of names (symbols)
+to ignore.
+@end deffn
 
 @menu
 * Core Lint::

diff --git a/src/devops/devops.pkg b/src/devops/devops.pkg
index 825f9289943ba6f0455443e1101760a3f344e255..f37365c92de68f223742c38a8169f98727219b2d 100644 (file)
--- a/src/devops/devops.pkg
+++ b/src/devops/devops.pkg
@@ -42,9 +42,13 @@ Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
          devops:build
          devops:make)
   (export (devops)
+         core-lint-hook
          host
          main
          plugin
+         plugin-directory
+         plugin-lint-hook
+         plugin-name
          project-name
          tag-options
          make-configuration))

diff --git a/src/devops/devops.texi b/src/devops/devops.texi
index 28c0b8e90c19f5430e81b73f0b13a2318b0af67d..b496adc0811922c2a627a44e3a7de3a0a315f98f 100644 (file)
--- a/src/devops/devops.texi
+++ b/src/devops/devops.texi
@@ -77,7 +77,7 @@ Documentation License.''
 MIT/GNU Scheme Pucked Developer Operations (devops) is a system of
 code for managing The Source of MIT/GNU Scheme Pucked and its plugins.
 A large part of this is a build system that does lint-like checks for
-consistency in and between core and plugin source code and
+consistency between core and plugin source code and
 documentation.  This devops plugin is also a developer's manual
 describing the build system and addressing implementation issues like
 just how is MIT/GNU Scheme Pucked.

diff --git a/src/devops/lint.scm b/src/devops/lint.scm
index 9b3e00c7b7bfb7f4e3cd2f9c54569595aa04f984..548b9bb27c1b65ebbe54ef800bdb43ef78d2e88f 100644 (file)
--- a/src/devops/lint.scm
+++ b/src/devops/lint.scm
@@ -25,9 +25,6 @@ Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
 ;;; See devops.texi for complete details.
 
 (define (plugin-deffn-lint plugin pkg exceptions)
-  ;; If the plugin contains a .texi file with the same name, check
-  ;; that it has a @deffn for every binding exported to () or PKG
-  ;; except for EXCEPTIONS.
   (let* ((name (plugin-name plugin))
         (dir (plugin-directory plugin))
         (file (string dir"/"name".texi")))