JOSS Review: Documentation

[lheagy]

Originally from @jochym in openjournals/joss-reviews#440

There is only very limited API documentation for two functions. Judging from the simplest example, even this simplest usage requires calling additional API functions (multiphonon.sqe.interp). The only functional documentation is a tersely commented notebook which I was unable to run (see above).

[yxqd]

Will add some more API documentation

[yxqd]

List of functions to add API doc or to expose API doc:

• https://github.com/sns-chops/multiphonon/blob/61dd792aa3695281240abf51e9151a308e86163c/multiphonon/redutils.py#L1
• https://github.com/sns-chops/multiphonon/blob/61dd792aa3695281240abf51e9151a308e86163c/multiphonon/backward/singlephonon_sqe2dos.py#L10
• Plotting methods in https://github.com/sns-chops/multiphonon/blob/61dd792aa3695281240abf51e9151a308e86163c/multiphonon/backward/plotutils.py
• https://github.com/sns-chops/multiphonon/blob/61dd792aa3695281240abf51e9151a308e86163c/multiphonon/forward/__init__.py#L7
• https://github.com/sns-chops/multiphonon/blob/61dd792aa3695281240abf51e9151a308e86163c/multiphonon/forward/phonon.py#L21
• https://github.com/sns-chops/multiphonon/blob/61dd792aa3695281240abf51e9151a308e86163c/multiphonon/forward/phonon.py#L30
• https://github.com/sns-chops/multiphonon/blob/61dd792aa3695281240abf51e9151a308e86163c/multiphonon/sqe/__init__.py#L27

[jochym]

API

• Try to aim for the level of documentation used in scipy - such that users will have all necessary data to use your code.
• Please add some overview paragraphs to the docs to help users orient themselves.

Functional docs

The notebook tutorial is a very good idea and it is mostly fine (except it did not run on my system). I have only one comment regarding the contents: please consider adding more narrative material, some overview and step by step explanation. Remember you are writing for a novice user not an expert (they can figure out everything without your help).

[yxqd]

@jochym Please check the new API doc at http://sns-chops.github.io/multiphonon/. We added API docs for the methods intended for users. We also added a brief introduction.

We added comments to the jupyter notebook, and added one more example to show users how to work directly from numpy arrays of I(Q,E) spectrum.

[jochym]

• The api docs are greatly expanded and much better now.
• Can you @yxqd declare that every function in your public API is documented? This is important - there should be no undocumented parts of the API which are required for the functionality of the software. I am fine with undocumented internal interfaces but strongly advise against keeping substantial APIs (external or internal) undocumented.
• The additional example is welcomed but should be mentioned in the readme and explained in the docs
• I still cannot find any functional documentation of the package. I think that this is fairly important - the beginner user has no clear indications where to start. There is no "principles of operation" text and no explanation of rather cryptic and non-standard steps in the notebook. The learning curve for someone not familiar with mandit will be rather steep. Such docs should be included in the RTD documents.

[yxqd]

Thanks @jochym.

• Great!
• I just went through the API doc and yes every public function is documented. There are some functions that may be worth considered to be made public in the future, but I don't think they are important for this version of the software.
• Added explanation: a89cf94
• That particular notebook is intended for users who are not programmers and that is why we provide some small UI widgets in the notebook to guide the users through the procedure, and it is hiding a lot of the technical details. I will add another notebook to make it clear what is going on behind the UI widgets.

[jochym]

The additional notebook will be a very welcomed addition.