Why use contents.m file in package structure

Question

Jeremiah Sullivan 2024-1-26

0
链接

此问题的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/2074676-why-use-contents-m-file-in-package-structure

编辑： Jeremiah Sullivan 2024-1-31

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?

0 个评论
显示 -2更早的评论隐藏 -2更早的评论

请先登录，再进行评论。

请先登录，再回答此问题。

Answer 1

Fangjun Jiang 2024-1-26

1
链接

此回答的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/2074676-why-use-contents-m-file-in-package-structure#answer_1397896

编辑：Fangjun Jiang 2024-1-26

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 个评论
显示 2更早的评论隐藏 2更早的评论

Stephen23 2024-1-26

编辑：Stephen23 2024-1-26

"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 2024-1-26

See my inserted comments above.

Jeremiah Sullivan 2024-1-31

编辑：Jeremiah Sullivan 2024-1-31

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.

请先登录，再进行评论。