Why use contents.m file in package structure

10 visualizzazioni (ultimi 30 giorni)
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?

Risposta accettata

Fangjun Jiang
Fangjun Jiang il 26 Gen 2024
Modificato: Fangjun Jiang il 26 Gen 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 Commenti
Fangjun Jiang
Fangjun Jiang il 26 Gen 2024
See my inserted comments above.
Jeremiah Sullivan
Jeremiah Sullivan il 31 Gen 2024
Modificato: Jeremiah Sullivan il 31 Gen 2024
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.

Accedi per commentare.

Più risposte (0)

Categorie

Scopri di più su Environment and Settings in Help Center e File Exchange

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!

Translated by