Opened 8 years ago

Last modified 8 years ago

#122 new enhancement

Code documentation

Reported by: Ian Hinder Owned by: mthomas
Priority: minor Milestone:
Component: SimFactory Version:
Keywords: Cc:


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.

Attachments (1)

ProtectInit.patch (518 bytes) - added by Ian Hinder 8 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 Changed 8 years ago by Ian Hinder

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.

comment:2 Changed 8 years ago by Erik Schnetter

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.

comment:3 Changed 8 years ago by Ian Hinder

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

Changed 8 years ago by Ian Hinder

Attachment: ProtectInit.patch added

comment:4 Changed 8 years ago by Ian Hinder

This attachment ensures that the main simfactory program does not run unless the file is executed as a script, rather than imported. This was suggested in the pydoc documentation:

OK to commit?

comment:5 Changed 8 years ago by Erik Schnetter

Please commit.

Is there a way to generate an index.html as well?

comment:6 Changed 8 years ago by Ian Hinder

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.

Modify Ticket

Change Properties
Set your email in Preferences
as new The owner will remain mthomas.
Next status will be 'review'.
as The resolution will be set.
to The owner will be changed from mthomas to the specified user.
Next status will be 'confirmed'.
The owner will be changed from mthomas to anonymous.

Add Comment

E-mail address and name can be saved in the Preferences.

Note: See TracTickets for help on using tickets.