The piam-scm-interface from gabriel-abrahao

Use numpy-style docstrings for function documentation

Hi Gabriel,

You have added quite useful documentation for your functions, eg:

Lines 22 to 33 in 7c5ebbb

    
           # Writes a dict as a single parameter in a new GDX file 
        
           # vargamsname: 
        
           #   GAMS name of the variable 
        
           # vardict: 
        
           #   dictionary with the values. The keys define a new Set called gamssetname 
        
           # vartext: 
        
           #   explanatory text (optional) 
        
           # gamssetname: 
        
           #   name of the GAMS Set that will be built from vardict's keys 
        
           # outfname: 
        
           #   output GDX file name 
        
           def write_gdx_parameter_from_dict(vargamsname, vardict, gamssetname, outfname, vartext = ""):

However, at the moment the documentation is in the form of comments, which is non-standard. A standard way of specifying documentation is using numpy-style docstrings. For example, the documentation for write_gdx_parameter_from_dict using numpy docstring style would look like this:

def write_gdx_parameter_from_dict(vargamsname, vardict, gamssetname, outfname, vartext = ""):
    """Writes a dict as a single parameter in a new GDX file

    Parameters
    ----------
    vargamsname: str
        GAMS name of the variable
    vardict: dict
        Dictionary containing the values. The keys define a new Set called gamssetname.
    gamssetname: str
        Name of the GAMS Set that will be built from vardict's keys
    outfname: str
        output GDX file name
    vartext: str, default empty string
        ???
    """
    …

Using an integrated development environment like pycharm or VS Code, the documentation is then displayed inside tool tips etc., and also on the ipython console, you get nice documentation using ?:

In [3]: write_gdx_parameter_from_dict?
Signature:
write_gdx_parameter_from_dict(
    vargamsname,
    vardict,
    gamssetname,
    outfname,
    vartext='',
)
Docstring:
Writes a dict as a single parameter in a new GDX file

Parameters
----------
vargamsname: str
    GAMS name of the variable
vardict: dict
    Dictionary containing the values. The keys define a new Set called gamssetname.
gamssetname: str
    Name of the GAMS Set that will be built from vardict's keys
outfname: str
    output GDX file name
vartext: str, default empty string
    ???
File:      ~/<ipython-input-2-dbb33317714f>
Type:      function

Cheers,

Mika

gabriel-abrahao / piam-scm-interface Goto Github PK

piam-scm-interface's People

Contributors

Watchers

piam-scm-interface's Issues

Use numpy-style docstrings for function documentation

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent

	# Writes a dict as a single parameter in a new GDX file
	# vargamsname:
	# GAMS name of the variable
	# vardict:
	# dictionary with the values. The keys define a new Set called gamssetname
	# vartext:
	# explanatory text (optional)
	# gamssetname:
	# name of the GAMS Set that will be built from vardict's keys
	# outfname:
	# output GDX file name
	def write_gdx_parameter_from_dict(vargamsname, vardict, gamssetname, outfname, vartext = ""):