Why use contents.m file in package structure
5 views (last 30 days)
Show older comments
Jeremiah Sullivan
on 26 Jan 2024
Edited: Jeremiah Sullivan
on 31 Jan 2024
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.
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?
0 Comments
Accepted Answer
Fangjun Jiang
on 26 Jan 2024
Edited: Fangjun Jiang
on 26 Jan 2024
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.
4 Comments
More Answers (0)
See Also
Categories
Find more on Environment and Settings 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!