How long is too long for function help text?

I have a function with about a hundred listed operating modes, accepted parameter ranges for each, and a fair chunk of explanation totaling about 340 lines. I've done my best to be concise, but it's still a lot.

I had originally thought to offload a lot of the details into web documentation, but looking at the logs, I know nobody uses it.

I know this is probably a pretty subjective question; everyone has their environment configured differently and has different expectations. Beyond that, is there some point at which the amount of help text in a function becomes problematic for most users? Are there other instances of bulky documentation already out there?

[DGM]

I asked this nearly 8 years ago. In that time, the function in question has been split into separate blender and compositor tools for sake of maintenance, but the main user-facing tool still carries the synopsis for everything, amounting to a bit over 700 lines. Core usage information is up front, then a long table, and then descriptive details for specific modes and families of modes. It's a lot, but it's fairly compartmentalized. Still, it always bothered me that this is the price of trying to be comprehensive.

Today, I opened PsychImaging() from PTB -- a editor-lagging 5k line file with a synopsis nearly 1700 lines long. I don't really feel so bad now.

Answer 1

[Star Strider]

If you have a complicated function, you likely need to have extensive documentation. One item I would include is to list a sort of ‘table of contents’ at the beginning with a short (one or two line) description of each, so the user can then scroll down to the appropriate section.

If you’re going to upload your function to the File Exchange, I would include example code demonstrating how to use it in the File Exchange description. (Leave four line feeds between paragraphs, or the text will run together.)

[DGM]

In the help text, most of the space is taken up with lists and explanations for the accepted values for two parameters: i.e. it's mostly just two tables referred to by the synopsis at the top, so that much is pretty much already there. It has simple structure; it's just voluminous.

As far as being elaborate with the FEX description, I'm already up against the character limit just listing the supported modes with no description or examples. You're right though, that'd be a great place for a detailed introduction.

[Star Strider]

My only other suggestion is to upload a PDF file with all the details and explanation you want, including examples as to what it does and how to use it. They’re easy to download, save, and read, and you can incorporate hyperlinks in them.

What does your function do?

[DGM]

The function in question is part of a dubious image manipulation toolbox I've been working on. As more detailed examples would include images, I decided against going with a PDF except for an index of contour plots. Otherwise, going that route would force me to ask the question "how many MB is too much for a FEX archive?". The web documentation is about 50MB.

My original approach was to consider help as a place to explain concept and usage, while leaving most examples to the web documentation.

This is the file as is currently uploaded. I'm rewriting to try to make it clearer since I'm making major changes to its behavior.

half-finished current revision

[Star Strider]

I would add the tag ‘image processing’ to be sure Image Analyst sees your post. He likely has more relevant ideas than some of the rest of us do, and has written a number of FEX submissions as well.

Answer 2

[Steven Lord]

I'd look at this a little differently. You have a single function with about one hundred (listed == documented?) operating modes. That sounds to me like a clear violation of the single responsibility principle. Just because all of those "operating modes" are related doesn't necessarily mean they all need to be part of the same function.

For example, look at the functions that MATLAB alone contains for reading data. Do we really need csvread AND dlmread AND textscan AND xlsread AND imread AND ncread AND ... or would one function named something like read have been sufficient? Splitting apart the "reading a file" functionality into individual functions for individual formats lets us have each function accept only those options that are relevant for their format without having xlsread needing to know about (and ignore) imread's PixelRegion option for JPEG 2000 files, for example. [To be honest, I feel imread is somewhat in violation of Single Responsibility as well. But redesigning it would be nigh impossible without creating a mass of backwards incompatibility.]

Long story short (too late, I know) are you sure you've written a function or have you written (the beginnings of) a small toolbox?

[DGM]

... yes, it's the core of a toolbox. It's a tool to blend/composite images or image arrays. It's one main file containing a handful of functions, plus external conversion functions in the same archive. The usage isn't so varied between modes as something like imwrite().

Part of the utility of keeping it as one function is simply that the modes remain parametric. If i need to compose a layered stack of images, i would otherwise end up with the function name itself being a parameter varied in a loop.

I could split apart the blend/compositing functionality, but that would end up complicating usage, since compositing (e.g. with GIMP compatibility) requires knowledge of the parameters applied to the blend operation.

It would turn this: R=imblend(FG,BG,1,'overlay');

into something like this: R=compose_gimp(blend_overlay(FG,BG,1)),FG,BG,'atop');

Can the required information be passed between the two as a struct or multiple arguments? Could the individualized blend function call the individualized composite function itself? Sure, but the typical use case still turns into a bunch of eval() statements. It'd save about 6ms of overhead, but on a 200ms operation, I'm not worried.

I know I'm building a swiss army knife, and that objective involves compromises. I'm working on the assumption that if someone truly needs it to only ever do one thing, they can chop out the part they need and make their own lean single-purpose function.

Of course, none of this mentions the usability of the help documentation -- which was the question.

I feel that much of the utility of having things described in one place is that they can be browsed and compared. While splitting into many small functions would certainly give more room to talk about any one in its synopsis, it would end up burying the details across many separate texts which all become mostly repetition of the same common usage options.

I could chop out the more descriptive texts or find some route around the size of the help text as it is, but I'm not considering splitting it. It'd break compatibility anyway.

I was just asking if scrolling that much is a prohibitive bother.