Docstring conventions: what docstring format should I use?

fastai fastai dev
1

Hi *,

I am new in contributing to fastai and I am wondering what if the docstring convention?
As an example, I’ve created pull request: https://github.com/fastai/fastai/pull/1022

and as Ilia mentioned in the discussion thread about this pull request: Iterative computations of confusion matrix fastai codebase doesn’t document function args in the docstings. I’ve used to more advanced docstrings like this(which does not mean it is better in general):

        """    
        description.
        :param param1: description.
        :param param2: description.
        :return: return description
        """

I haven’t found any discussions about it, so maybe I am missing some information, but where should I document parameters, especially if I add one like in this pull request?

I appreciate your answers/ideas/suggestions etc!

1 Like
2

The docstrings should take the minimum amount of space (one line is best) and explain in sentences what the function does, with the arguments between backquotes. That’s the format that will work best with our documentation framework. Note that the argument and the return should be type-annotated. Example:

def open_image(fn:PathOrStr)->Image:
    "Return `Image` object created from image in file `fn`."
2 Likes
3

Also note that the main documentation should then be added as a real working code example in fastai_docs/docs_src .

1 Like
4

Jeremy,
that you for your reply. I am a bit struggling with adding example to fastai_docs/docs_src . On one hand, there is already a vision.learner.ipynb notebook where I could add my documentation/example. On another hand, it is not up to date and does not work with the latest fastai code. What would you suggest? add a new notebook even though I am adding just a relatively minor feature to the module?

5

I don’t understand that part: all the docs work on current code, they have been tested with the last release.

If you’re talking about the feature you want to add, then yes, writing the docs will come in a second time once the first PR is merged.

6

This is what I get locally when trying to run vision.learner.ipynb:
I’ve checked the current code to be sure that my fastai_doc uses latest fastai version.

fastai_error
fastai_error.PNG1244×1160 75.5 KB

this line in fastai/vision/learner.py
—> 49 ds.set_item(img)

calls set_item of ImageClassificationDataset, which does not have it.

All my changes are backward-compatible and could not cause an error, but I double checked that.

7

If you don’t have this function, it’s definitely because you don’t have the latest version. ImageClassificationDataset is an ImageDataset which is a LabelDataset which is a Datasetbase which has a set_item function :wink:

1 Like
8

You can use the snippet at the top of this to check fyi:

1 Like
9

yes, indeed. Stupid I, jumped too early in the conclusions.

10

Thank you very much, Jeremy, it helped me to see that my doc_src repo point to wrong fastai path with older version.

2 Likes