Documentation for compile.el and grep.el?

[Nick Roberts <nickrob@snap.net.nz>]

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.

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.

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.

Nick