Docstring format

[DonJayamanne]

From @IgorNovozhilov on April 24, 2017 8:20

Hi, I have a question.

What is the documentation standard parameters supported for mo method?

At first I thought it was NumPy, but I have that kind of problem:

But the standard itself is described without spaces to describe the parameters and types:
http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

Copied from original issue: DonJayamanne/pythonVSCode#908

[DonJayamanne]

@IgorNovozhilov
Apologies for not getting back to you on this. Been focusing on more critical issues and in the process managed to over look simple items. I'll try to look into this sometime this month.

[DonJayamanne]

From @BlacKCaT27 on October 23, 2017 20:36

Don,

If you can maybe point me in the general direction of where to start for resolving this and adding support, I can at least start exploring potential solutions if you're tied up on other things. I would definitely love to have proper docstring formatting support, and would love to help get there.

[DonJayamanne]

All of the magic takes place here https://github.com/DonJayamanne/pythonVSCode/blob/master/src/client/providers/jediHelpers.ts#L51

@BlacKCaT27 thanks for volunteering to help in this space.

I think as a first step, I'd like to identify the formats of doc string(s) you intend on adding support for.
There's no point in supporting all formats under the sun, just a maintenance nightmare.

[DonJayamanne]

From @BlacKCaT27 on October 24, 2017 14:20

This might be a bit overkill, but in my head I'm thinking of a small abstraction layer on top of the various formats. If we identify the total set of features offered by these formats (section headers, code blocks, lists, etc), it should be a relatively simple task to restructure the code to identify and apply features to the markdown based on a user-configured format setting (using reST as the default since that implementation already appears to mostly exist).

Going this route, we could easily add support for additional formats by simply creating a format-specific implementation class for the feature-set then injecting them into the jediHelper at runtime.

In terms of initially supported formats, my vote would be to start with reST since that's already there and would just need to be refactored, and additionally google docstring formatting support since that spec is relatively popular and clearly defined/documented.

[DonJayamanne]

From @BlacKCaT27 on October 24, 2017 14:33

Also, I've noticed a similar issue which I'm commenting here as it's related to the exact same root cause (bad formatting handling): escape characters are not being handled properly. Example:

docstring text:
SaveSimulation(r'E:\aSimFile.sim') and SaveSimulation('E:\aSimFile.sim') will work, while just SaveSimulation('E:\aSimFile.sim')

tooltip displays:
SaveSimulation(r'E�SimFile.sim') and SaveSimulation('E \aSimFile.sim') will work, while just SaveSimulation('E:�SimFile.sim')

I'll have to dig into the format specifications more to see if they call out specific details around escape sequences, but my 'gut feeling' is that they should be treated as regular characters and not be escaped without some sort of explicit markup instructing the formatter to do so.

[brettcannon]

Closing as a duplicate of DonJayamanne#38