search

florianschanda / miss_hit

MATLAB Independent, Small & Safe, High Integrity Tools - code formatter and more
GNU General Public License v3.0
170 stars 20 forks source link

Docstring format enforcer and generator #211

Open jand271 opened 3 years ago

jand271 commented 3 years ago

What kind of feature is this?

MISS_HIT component affected Choose one or more of the below:

Describe the solution you'd like Mathworks provides a system to read help doc strings for functions.

It would be nice if miss_hit would enforce the following in my continuous integration workflow: (1) every function and class has a docstring (2) every function and class has a docstring compatible with the Matlab help feature.

In addition, it would be nice to miss_hit included a function to autogenerate those doc strings (including variable arguments, e.g., via the arg parser functions).

I can't seem to find a good tool online that do the above. Apologies if I didn't look hard enough.

florianschanda commented 3 years ago

Right. This sounds like a reasonable feature request :)

I think the most likely place this check will go into is MH Lint, since a missing docstring is not something that can be fixed automatically. Checking that the docstring in question conforms to some established pattern will also be a MH Lint check (we do a limited form of that already on copyright notices).

As to auto-generating the docstring, that is something I could consider later but right now I can't do it for technical reasons. Specifically to understand parameter types and deciphering varargs will require some form of semantic analysis. This work is planned (as it will be super important to stronger analysis in MH Lint) but quite complex, so please don't expect anything done on that front in the short-term.

florianschanda commented 3 years ago

Oh, and sorry for not replying sooner. I have a mad busy few weeks for now so did not find much time to look at github :)

jand271 commented 3 years ago

np....very busy here in grad school rn. Your tool is helping me enforce good coding practices for the undergraduate researchers coding for me. Thanks you!

Any automated doc string enforcement would be amazing!

florianschanda commented 3 years ago

Ah yes, getting students to indent, I remember that problem ;) Teach them Python it fixes that particular problem XD

Remi-Gau commented 3 years ago

well I have always used the ctrl + a ctrl + i shortcuts of matlab IDE to do the indent for me. :smile:

now I just need to make sure the setting is the same as for MISS_HIT.

jand271 commented 3 years ago

Lol, I do most of my Matlab dev in sublime...I added mh to my sublime builder via ⌘B.

jand271 commented 3 years ago

Do you think this could make the next release?

jand271 commented 3 years ago

Also, this ST package makes context-aware Matlab doc autogeneration. Might be useful start for mh.

https://packagecontrol.io/packages/AutoMatlab

florianschanda commented 3 years ago

That is a good pointer, thanks