- removed comment
Code documentation
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.
Keyword:
Comments (6)
-
reporter -
- 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.
-
reporter - removed comment
Sorry - I had forgotten a change to the sim.py file which fixes this in my version. I will include it in the patch.
-
reporter - removed comment
This attachment ensures that the main simfactory program does not run unless the sim.py file is executed as a script, rather than imported. This was suggested in the pydoc documentation:
http://docs.python.org/library/pydoc.html
OK to commit?
-
- removed comment
Please commit.
Is there a way to generate an index.html as well?
-
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.
- Log in to 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.