Added class and module docstrings #174

tracetidwell · 2021-01-29T18:45:25Z

class docstrings are created under the class definition. They read parameters from the init() method and scan the entire class for attributes. Both parameters and attributes are listed.

module docstrings are created at the first line of the script. They scan the entire file and list out all top-level classes and methods defined therein.

All tests are passing, and I added a few unit tests and integration tests. I am not an expert at TypeScript, so this might can be improved, but I've been using this on my code for a few months now with no problems.

…tring into feature/module_docstring

…tern allows use of getFunctionName() method; parseParameters: parseExceptions: [] inside docstringType === class

Feature/module docstring

updated changelog; cleaning up code

refactoring for code climate compliance

refactoring

still simplifying get_definition

refatoring...

one more try

NilsJPWerner · 2021-02-04T04:56:50Z

Hi this pr looks fantastic! I will review it this weekend.

bnonni · 2021-02-25T17:30:04Z

@NilsJPWerner any updates on your side?

michaeloliverx · 2021-03-05T11:51:36Z

Nice work this would be awesome!

NilsJPWerner

Sorry for the long delay. I finally found time to check your pr. It looks very good on inspection. There are a few things that need cleaning up and adding, and I am going to try it out for a few days to check that there are no regressions.

src/docstring/templates/ncr.mustache

NilsJPWerner · 2021-03-08T03:41:25Z

src/test/run_integration_tests.js

@@ -0,0 +1,75 @@
+"use strict";


What is this? Were the existing integration tests not working?

I'm not actually sure. I did not do that; perhaps my colleague who did a little work did. I will find out.

if that was me, i'm not sure why i put it there. if the tests run without it, then remove it. i would imagine it was me being nit-picky bc my extension was telling me to add it or something

src/test/parse/get_body.spec.ts

src/docstring/docstring_factory.ts

package.json

NilsJPWerner · 2021-03-08T04:24:26Z

src/parse/get_docstring_type.ts

@@ -0,0 +1,18 @@
+export function getDocstringType(functionDefinition: string, linePosition: number): string {


I think we should turn the return type into a string literal type so that we restrict to only types we define.

NilsJPWerner · 2021-03-08T04:26:11Z

src/parse/get_docstring_type.ts

+    }
+
+    else  {
+        return "method";


I think this should be renamed to function since not all functions are methods.

NilsJPWerner · 2021-03-08T04:28:06Z

src/parse/parse_parameters.ts

+            returns: undefined,
+            yields: undefined,
+            exceptions: [],
+            classes: parseMethods(body, /(?:class)\s/),


I think these should be split into 2 functions instead of passing a regex into it

NilsJPWerner · 2021-03-08T04:31:12Z

src/parse/parse_parameters.ts

+        }
+        let var_ = match[1];
+        let type_ = guessType(match[1]);
+        if (!containsAttribute(attributes, var_) && !containsAttribute(args, var_) && !containsAttribute(kwargs, var_)) {


I'm a bit confused by this? What is going on here?

NilsJPWerner · 2021-03-08T04:33:42Z

src/test/integration/python_test_files/file_7_output.py

+class TestClass(object):
+    """[summary]
+
+    :param arg1: [description]


I think we need an integration test for attributes.

lieutdan13 · 2021-10-04T19:47:50Z

@tracetidwell thank you for contributing to this project. This feature would help out so many of us that have expressed interest in issue #27. It would be really helpful if you addressed the comments that the repo owner @NilsJPWerner has requested, then he can followup and get this merged and published for us all to use :)

tracetidwell · 2022-02-04T20:42:53Z

After way, WAY too long, I am going to finish this. I resolved a number of issues, left comments on a couple others, and need to work on the rest. If this is not being maintained or doesn't seem worth it, please let me know.

bnonni · 2022-02-04T21:08:40Z

I haven't touched this repo in years, but I think I still have the repo cloned locally. @tracetidwell let me know if you need something from me. would love to help get this completed and merged.

trycoast · 2022-04-25T21:55:36Z

Any news on this?

MaddyGuthridge · 2022-06-29T09:12:01Z

Bumping this again? Would love to see this merged? If not, does anyone know any alternatives?

NilsJPWerner · 2022-06-29T15:17:17Z

If @tracetidwell or someone else wants to pick up the PR again or start fresh I would be happy to review and merge. Right now I am focused on adding the ability to update docstrings, and so work on module and class docstrings will have to come afterwards.

silopolis · 2022-09-13T17:28:32Z

WANT!

NathanNull · 2022-10-04T02:48:29Z

This would be super nice, someone finalize this and add it

trycoast · 2022-10-04T08:37:17Z

Yes, please make this happen 🙏

FrankC01 · 2023-02-01T09:39:59Z

Really, sitting in this state for over two years? I don't think this is being maintained any longer.

ishandandekar · 2023-02-04T11:01:18Z

Need this please, ASAP!

mjspeck · 2023-05-08T21:48:35Z

Any updates on this?

yuval1337 · 2023-06-08T13:31:20Z

Did anyone perhaps forked and added this feature? I would love to use it!
It appears the repo's owner forsaken this project, as there were no pushes made in over a year.

CmpCtrl · 2024-05-05T14:54:57Z

This still seems like useful functionality. Is there any chance of it being introduced? What about alternatives?

DrJStrudwick · 2024-08-15T10:30:58Z

@NilsJPWerner @PhilipNelson5 @tracetidwell Any movement on this? This is a really cool tool and this PR would be a great addition. If this tool as a whole is no longer being maintained then fair enough :)

efrainMesia · 2024-09-07T06:03:20Z

@tracetidwell @NilsJPWerner any upate on this?
is there any way of how to help here?

tracetidwell and others added 28 commits April 26, 2020 12:05

added functionality for module docstring

3f07a57

adding regex expressions for classes & methods

a8f0ef3

Reversing regex

6ad28ab

removing a global flag

07cb44e

added src/parse/get_class_name to fix regex issue for classes

125110b

Merge branch 'feature/module_docstring' of github.com:bnonni/autoDocs…

11a2efa

…tring into feature/module_docstring

added src/parse/get_class_name to fix regex issue with classes

180141e

functionality for module and class docstrings. looks good, needs testing

739b166

pushing fixes to broken tests

cff0855

parseAttributes: new regex pattern; parseClasses: different regex pat…

d099316

…tern allows use of getFunctionName() method; parseParameters: parseExceptions: [] inside docstringType === class

getFunctionName: adding diff regex for both class and method

209f1ed

pulled most recent master; working on tests

30537c3

mergingin everything into new branch

0d7603e

passing unit tests; failing integration tests

e620d1f

all unit tests and integration tests passing!

0b08830

Merge pull request #1 from bnonni/feature/module_docstring

1ba0736

Feature/module docstring

updated changelog; cleaning up code

29442b7

Merge pull request #2 from bnonni/feature/module_docstring

1b2c384

updated changelog; cleaning up code

refactoring for code climate compliance

c8ad667

Merge pull request #3 from bnonni/feature/module_docstring

b178d92

refactoring for code climate compliance

refactoring

187d850

Merge pull request #4 from bnonni/feature/module_docstring

1f7f3ef

refactoring

still simplifying get_definition

b6eb8a4

Merge pull request #5 from bnonni/feature/module_docstring

24de229

still simplifying get_definition

refatoring...

63e67d1

Merge pull request #6 from bnonni/feature/module_docstring

0dac472

refatoring...

one more try

5b43992

Merge pull request #7 from bnonni/feature/module_docstring

973fb88

one more try

NilsJPWerner reviewed Mar 8, 2021

View reviewed changes

NilsJPWerner force-pushed the master branch from 311c5f4 to f7bc9f4 Compare March 3, 2022 20:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added class and module docstrings #174

Added class and module docstrings #174

tracetidwell commented Jan 29, 2021 •

edited

Loading

NilsJPWerner commented Feb 4, 2021

bnonni commented Feb 25, 2021

michaeloliverx commented Mar 5, 2021

NilsJPWerner left a comment

NilsJPWerner Mar 8, 2021

tracetidwell Feb 4, 2022

bnonni Feb 4, 2022

NilsJPWerner Mar 8, 2021

NilsJPWerner Mar 8, 2021

NilsJPWerner Mar 8, 2021

NilsJPWerner Mar 8, 2021

NilsJPWerner Mar 8, 2021

lieutdan13 commented Oct 4, 2021

tracetidwell commented Feb 4, 2022

bnonni commented Feb 4, 2022

trycoast commented Apr 25, 2022

MaddyGuthridge commented Jun 29, 2022

NilsJPWerner commented Jun 29, 2022

silopolis commented Sep 13, 2022

NathanNull commented Oct 4, 2022

trycoast commented Oct 4, 2022

FrankC01 commented Feb 1, 2023

ishandandekar commented Feb 4, 2023

mjspeck commented May 8, 2023

yuval1337 commented Jun 8, 2023

CmpCtrl commented May 5, 2024

DrJStrudwick commented Aug 15, 2024

efrainMesia commented Sep 7, 2024

		@@ -0,0 +1,18 @@
		export function getDocstringType(functionDefinition: string, linePosition: number): string {

Added class and module docstrings #174

Are you sure you want to change the base?

Added class and module docstrings #174

Conversation

tracetidwell commented Jan 29, 2021 • edited Loading

NilsJPWerner commented Feb 4, 2021

bnonni commented Feb 25, 2021

michaeloliverx commented Mar 5, 2021

NilsJPWerner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lieutdan13 commented Oct 4, 2021

tracetidwell commented Feb 4, 2022

bnonni commented Feb 4, 2022

trycoast commented Apr 25, 2022

MaddyGuthridge commented Jun 29, 2022

NilsJPWerner commented Jun 29, 2022

silopolis commented Sep 13, 2022

NathanNull commented Oct 4, 2022

trycoast commented Oct 4, 2022

FrankC01 commented Feb 1, 2023

ishandandekar commented Feb 4, 2023

mjspeck commented May 8, 2023

yuval1337 commented Jun 8, 2023

CmpCtrl commented May 5, 2024

DrJStrudwick commented Aug 15, 2024

efrainMesia commented Sep 7, 2024

tracetidwell commented Jan 29, 2021 •

edited

Loading