Re: Feature request: Generate module docstrings from startproject and startapp actions

[Aymeric Augustin]

Hello Matthew,

I understand the suggestion, however, I’m afraid it priorizes the needs of the 
wrong audience. Experienced developers or teams who care about docstrings and 
pylint can use a custom project template for this use case. Conversely, 
newcomers who are still learning Django would likely leave a docstring stub 
untouched. I lost count of the number of copies of 
https://github.com/django/django/blob/master/django/conf/app_template/tests.py-tpl
 I git-rm’d over the years...

There’s no denying docstrings are useful, but many projects — even large ones — 
are doing just fine without adding one to every single module. I don’t believe 
Django should be exceedingly prescriptive in this regard because I’m afraid 
we’d just encourage the perversion of JavaDoc / PHPDoc / epydoc / etc., that 
is, docstrings written because they’re mandatory and add zero value, like 
"""This module defines the models for billing.”””. Well, it’s called 
`billing/models.py`, I knew that already.

If that requirement was found in PEP 8 or more widely followed by the 
community, I’d be more open to encoding it in the default project template. PEP 
257 sounds a bit self-serving there...

-- 
Aymeric.

> On 15 Sep 2016, at 10:47, Matthew Laney  wrote:
> 
> Hi,
> 
> Going through my code with pylint, I found that there is no way to filter by 
> the type of missing docstring. I.e. missing-docstring catches functions, 
> classes, methods, and modules. As a result, it gives a warning on for every 
> default Django file. Accordingly, I would like to suggest that the current 
> automatically generated comments of "Create your __ here" that are generated 
> for each file created by manage.py startapp be replaced with docstrings that 
> follow the PEP 257 convention. The second line of the specification: All 
> modules should normally have docstrings, and all functions and classes 
> exported by a module should also have docstrings.
> 
> Thanks,
> 
> Matt
> 
> -- 
> You received this message because you are subscribed to the Google Groups 
> "Django developers (Contributions to Django itself)" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to django-developers+unsubscr...@googlegroups.com 
> .
> To post to this group, send email to django-developers@googlegroups.com 
> .
> Visit this group at https://groups.google.com/group/django-developers 
> .
> To view this discussion on the web visit 
> https://groups.google.com/d/msgid/django-developers/29041c35-cc01-464c-9405-d84f1acbc62b%40googlegroups.com
>  
> .
> For more options, visit https://groups.google.com/d/optout 
> .

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/E6FBEAC7-2D2D-4ADF-94E2-A47B81B62617%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.

Feature request: Generate module docstrings from startproject and startapp actions

[Matthew Laney]

Hi,

Going through my code with pylint, I found that there is no way to filter 
by the type of missing docstring. I.e. missing-docstring catches functions, 
classes, methods, and modules. As a result, it gives a warning on for every 
default Django file. Accordingly, I would like to suggest that the current 
automatically generated comments of "Create your __ here" that are 
generated for each file created by manage.py startapp be replaced with 
docstrings that follow the PEP 257 convention. The second line of the 
specification: All modules should normally have docstrings, and all 
functions and classes exported by a module should also have docstrings.

Thanks,

Matt

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/29041c35-cc01-464c-9405-d84f1acbc62b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.