Why use contents.m file in package structure

My team maintains a modestly large code base separated into packages. Historically, contents.m files have been placed in (most) packages and (occasionally) updated alongside the code. Every .m file has a doc block which is updated (more frequently). I do not see any useful information in the contents.m files beyond the file name and and top level description.

According to this, if no contents.m file exists MATLAB will autogenerate the package documentation.

Given we require all .m files to be documented and we do not have any special information in our contents.m, isn’t this file entirely redundant? We recently dropped support for an older version of MATLAB, was this auto generation added recently?

Answer 1

[Fangjun Jiang]

contents.m is not redundant nor useless. It provides help info for the folder. You may have nice help text for individual .m files, but a "contents" page for the folder or toolbox is definitely helpful, like the "table of contents" page of a report or a book.

contents.m and the ability to auto generate contents.m have existed a long time in earlier versions. In the case when individual .m files don't have the right format or right info, you can create contents.m manually. If all your individual .m files are nicely formated and provide all needed info, then don't create the contents.m manually. Use help or doc to create it automatically and save it. All your changes in the individual .m files will be reflected. Saving the file rather than generating it every time when it is called is certainly more efficient, like saving a serch index file.

[Jeremiah]

OK, so if we have a requirement to create "nicely formatted" documentation "provid[ing]" all needed info" in our m-files, then manually typing (essentially copy-pasting the file-name and doc-block) into a contents.m is redundant?

Fangjun: Yes.

We have examples of the contents.m file saying "X takes a, b and makes c"; but the function actually takes "b, a and makes c". To me, having two conflicting pieces of documentation not great.

Fangjun: I agree.

I appreciate your answer, I realize this is pedantic and relatively unimportant, but I absolutely hate having superflouous and incorrect documentation hanging around.

Fangjun: You are in good shape since your team maintains a good set of .m files. Generate the contents.m file and check it. Inform the team to maintain the quality of the .m files since contents.m depends on them.

[Stephen23]

"We have examples of the contents.m file saying "X takes a, b and makes c"; but the function actually takes "b, a and makes c". To me, having two conflicting pieces of documentation not great."

Agreed. It is not really the purpose of CONTENTS.M to give detailed explanations of the input arguments, their input order, etc. As you note, that is exactly what the Mfile help is for.

Keep the CONTENTS.M explanations very high-level. Something like "X takes a, b and makes c" is far too low-level, but actually tells nothing about what the function is for, or why anyone would need to use it, or how it differs from any other functions that might have the same inputs and outputs. Much better would be something like the examples shown in the documentation here:

Edit or create a file

grabcode - Copy MATLAB code from published HTML

checkcode - Check files for possible problems

publish - Publish file containing cells to output file

These give absolutely no information about the inputs and outputs (and rightly so). The do however give the reader a good idea of what each function can do and when it might be used, without having to look at each function's help individually.

You do not give any specific information on your projects, but in general I think mentioning something like the algorithm/approach and goal would be a good overview, e.g. "Use blahblah to capture and save the blahblah data".

[Fangjun Jiang]

See my inserted comments above.

[Jeremiah Sullivan]

Thank you both! Something clicked between both of your explanations. I can at least explain why the contents file is useful and how we should maintain it going forward.