Re: Documentation for compile.el and grep.el?

["Eli Zaretskii" <eliz@gnu.org>]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Sat, 26 Feb 2005 16:43:33 +1300
> 
> building.texi says:
> 
> >    When the compiler process terminates, for whatever reason, the mode
> > line of the `*compilation*' buffer changes to say `signal' instead of
> > `run'.
> 
> In reality it seems to say `exit' when the compiler process terminates followed
> by the exit code in square brackets e.g [0] for normal, [1] for abnormal.

It could _also_ say `signal' if the subprocess was interrupted by a
signal.  But the text you cited is incorrect as it stands, and should
be fixed.

> Given the extensive changes to compile.el and grep.el, I'm surprised that the
> documentation has changed so little.
> 
> For example, compilation-directory-properties does something (mouse-2: visit
> current directory) but I don't know what it is. The relevant ChangeLog entry
> says:
> 
> > (compilation-first-column, compilation-error)
> > (compilation-directory-matcher, compilation-page-delimiter)
> > (compilation-mode-font-lock-keywords, compilation-debug)
> > (compilation-error-face, compilation-warning-face)
> > (compilation-info-face, compilation-line-face)
> > (compilation-column-face, compilation-enter-directory-face)
> > (compilation-leave-directory-face, compilation-skip-threshold)
> > (compilation-skip-visited, compilation-context-lines): New vars.
> 
> > (compilation-warning-face, compilation-info-face)
> > (compilation-message-face): New faces.
> 
> > (compilation-error-regexp-alist-alist): New constant.
> 
> > (compilation-face, compilation-directory-properties)
> > (compilation-assq, compilation-error-properties, compilation-start)
> > (define-compilation-mode, compilation-loop)
> > (compilation-set-window): New functions.
> 
> which is rather opaque, to say the least.

Some of these are mentioned in etc/NEWS, and they are not marked with
a "+++', which means the documentation was not yet updated to reflect
that change.  Someone will do that before the release.

> GDB developers are required to write documentation with their patches. I
> think that it makes little sense to check the manual in great detail if
> authors don't provide the relevant documentation in the first place.

In Emacs, we do this differently: a significant change should be
described in etc/NEWS when it is checked in.  Later, when the time
comes to release a version, one of the jobs that should be done is to
go through NEWS and update the documentation for every change.

It is also okay to change the docs right when the changes are
committed to CVS, but that is not required, and might actually be
worse if the person who wrote the code doesn't speak English well or
cannot write good documentation.