From: Matt Birkholz <matt@birchwood-abbey.net>
Date: Sun, 18 Mar 2018 01:12:08 +0000 (-0700)
Subject: devops: Document bindings in (devops).
X-Git-Tag: mit-scheme-pucked-x11-0.2.2~23
X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=b36f25049a6837976d7ded19573ac024c4b7bc51;p=mit-scheme.git

devops: Document bindings in (devops).
---

diff --git a/src/devops/build.texi b/src/devops/build.texi
index 291c4cbc0..fb5c2a002 100644
--- 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 825f92899..f37365c92 100644
--- 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 28c0b8e90..b496adc08 100644
--- 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 9b3e00c7b..548b9bb27 100644
--- 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")))