How long is too long for function help text?
2 views (last 30 days)
Show older comments
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?
0 Comments
Answers (2)
Star Strider
on 30 Jun 2016
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.)
4 Comments
Star Strider
on 30 Jun 2016
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.
Steven Lord
on 30 Jun 2016
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?
See Also
Categories
Find more on Text Data Preparation in Help Center and File Exchange
Community Treasure Hunt
Find the treasures in MATLAB Central and discover how the community can help you!
Start Hunting!