Code documentation

Create issue
Issue #122 new
Ian Hinder created an issue

In order to help new developers understand the code, the following would be useful:

  • Provide some sort of high-level overview of the internal components of simfactory. This could be in the form of a class diagram with annotations indicating what each class does, and its relationship to the other classes (inheritence/object membership etc). There must be tools for doing this for python and generating doxygen-type output.
  • Within the source code, provide at least a one-line comment for each function indicating what it does.
  • Ensure that the readmes etc in the repository are up-to-date, or at least remove any out-of-date information.


Comments (6)

  1. Ian Hinder reporter
    • removed comment

    In r1252 I have added a Makefile in the doc directory which uses pydoc to build developer documentation (it goes into doc/internal). The next step will be to annotate the source with sufficient information that this documentation is useful.

  2. Erik Schnetter
    • removed comment

    This Makefile does not seem to work for me. When I cd into the doc directory and call make, I first see the output

    wrote archive.html wrote archive.petashare.html wrote archive.uberftp.html wrote libutil.html wrote pyini.html wrote restartlib.html wrote sim-build.html wrote sim-info.html wrote sim-manage.html wrote sim-sync.html wrote sim-util.html

    and them simfactory says

    Usage: sim [args] command

    and prints its help desk. After this, the output continues

    pydoc: error: no such option: -w problem in sim - <type 'exceptions.SystemExit'>: 2 wrote simarchive.html wrote simdb.html wrote simdt.html wrote simenv.html wrote simlib.html no Python documentation found for 'simlog' wrote simopts.html wrote simproperties.html wrote simremote.html wrote simrestart.html wrote simsubs.html

    I have two versions of pydoc installed. By default, the one in /opt/local/bin is used. Its help text says that it does support the -w option.

  3. Ian Hinder reporter
    • removed comment

    Sorry - I had forgotten a change to the file which fixes this in my version. I will include it in the patch.

  4. Ian Hinder reporter
    • removed comment

    Committed. I don't think you can generate an index.html file. However, the sim.html file is a good starting point, and acts as a kind of index. There is another tool which works in a similar way to the html generation of pydoc called "pythondoc". We could see if that makes nicer-looking output. I would say the next step would be to add docstrings to all the functions.

  5. Log in to comment