It's not always easy to find the right level of documentation for a particular function, as I was reminded by this recent sci.image.processing post slamming the doc for imregionalmax and imextendedmax. (Hi, MH!)

I think the main issue is this: Which functions should include concept tutorial information in their reference pages? The reference pages for the functions above describe them in terms of precise but very brief definitions. For example, "regional maxima are connected components of pixels with a constant intensity value, and whose external boundary pixels all have a lower value." And that's about it; we don't give you any more context or explanation, nor do say anything about why you might want to use such function.

For many functions in MATLAB, I imagine that this level of documentation does not cause any problem at all. For an extreme example, consider the sin function. Our documentation tells you that the function returns the "circular sine." There's no further elaboration about what these terms mean, or why you might want to use sin. That's OK; virtually all MATLAB users learned all about the sine function in their trigonometry class back in high school.

Now consider imfilter, which performs two-dimensional and multidimensional convolution and correlation. The reference page contains no tutorial information about what filtering or convolution means, although there is a concrete example illustrating the use of imfilter to simulate motion blur. I think this is still probably OK, since we do assume our readers have some degree of familiarity with basic image processing concepts. We've never intended for our documentation to substitute for basic coursework in a particular domain.

For the functions imregionalmax and imextendedmax, though, I accept the documentation complaint as legitimate. These operations are not usually taught in a first course on image processing, and so it's reasonable to expect that many users would be encountering them for the first time in the Image Processing Toolbox. Our technical description of the regional maximum makes this concept harder to understand than it needs to be, and the extended maximum really needs diagrams and maybe a couple of examples to make it clear.

I plan to post explanations of these two operations here sometime soon. Depending on the feedback I get, I'll then make suggestions to our writer for expanding the reference pages.