CWM - How to develop modules - Missing Manual

DanC,

thank you very much for your help. Here an attempt to help to create a 
"developer" doc.

Le Lundi, 13 octo 2003, à 18:01 America/Montreal, Dan Connolly a écrit :
> "Cwm developers agree that all the tests have to pass before code is
> checked in. To run the tests, do make in the swap/test directory."
>   -- http://www.w3.org/2000/10/swap/doc/cwm.html#dev

Certainly, but the problem is that this part of the doc is not enough 
to understand the full architecture. Someone completely new will not be 
able to understand at all. (I'm this kind of person).


For example:
"""
+ cwm_xxx.py - builtin modules
	These are quite easy to add to
"""

That's wrong it's not easy to do :))) and there's a need for a full 
guide to create modules.


The only information I had to develop the trigo module for example:

1. Create a copy of the swap directory in your account.

2. How to create a new module.
	- Where do I put my module?
		always in /2002/10/swap/. ?
	For me it was: Look at the math module developed by Sean B. Palmer 
because it's about the same topic.
		For example cwm_trigo.py
		Rules for naming it cwm_name.py where name is the name of your module?
		How do I propose my module to the community?
		How do I proove it doesn't break anything?
		How do I add it in the official cvs tree?
		Where do I find the list of all modules already created by who.
		Who are the maintainer of every modules, last updated date?
		Is there a template to create a module?

***************************
	A possible template?
***************************
""" XXXX Built-Ins for CWM

Description of your modules
And references online to understand it and use it
Doc: 	http://wwww.example.org/modulename-doc.html
Test: 	http://www.w3.org/2000/10/swap/test/namefoo.n3

"""

__author__ = 'Firstname Lastname'
__cvsid__ = '$Id:  $'
__version__ = '$Revision:  $'
__all__ = []

from term import LightBuiltIn, Function, ReverseFunction
import types
from diag import progress

MODULENAME_NS_URI = 'http://www.w3.org/2000/10/swap/modulename#'

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
# #  Your classes for the modules Here
#
class BI_funcA(LightBuiltIn, Function):
     def evaluateObject(self, subj_py):
         """funcA(x)

         Does this or that with x."""
#  Here the function
#
#        return something


# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
#
#  Register the string built-ins with the store

def register(store):
     str = store.internURI(MODULENAME_NS_URI[:-1])
     str.internFrag('funcA', BI_funcA)

if __name__=="__main__":
    print __doc__.strip()
************************************************


3. Ok it seems not very complicated, mockup a module in the same way.
	I have created cwm_trigo.py

	- Check that you have the necessary modules
	- Check that you do not redefine things define elsewhere.
	- Don't forget to document your module in the code.
		For Example by pydoc. Try "pydoc cwm_name" for your
		cwm_name.py module
		so when you are in swap, you can do pydoc -p 8001
	and explore the modules documentation at http://localhost:8001/

	It's very hard to understand the structure of modules if you are not 
part of the project and so it's very hard to participate.

"""
	class BI_acos(LightBuiltIn, Function):
		def evaluateObject(self, subj_py):    	
			"""Return the arc cosine (measured in radians) of x."""
			return acos(numeric(subj_py))
"""

	Why a class has often this form?
	Here a document on the architecture is definitely missing, 
specifically because cwm is becoming more and more important.
	What's a Function and a ReverseFunction?

(Things that Tim told me in a mail and  on IRC without really being 
sure what they all mean.)

4. When do you create a Namespace and how do you do it?
	For my example I have used the math namespace because it seems to be 
logical.
	MATH_NS_URI = 'http://www.w3.org/2000/10/swap/math#'
	But in a more general case:
		- Where is the list of all namespace already created?
		- How do I choose the name for a new namespace? (rules for naming)

5. Create a Schema?

	- Where?
		http://www.w3.org/2000/10/swap/modulename.n3
	- How? Template?
*****************
Template?
******************
# Schema for CWM's @@FEATURE@@ built-ins
# Author: First Last
# Email:
#
# $Id: $

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix daml: <http://www.daml.org/2001/03/daml+oil#> .
@prefix log: <http://www.w3.org/2000/10/swap/log#> .
@prefix string: <http://www.w3.org/2000/10/swap/string#> .
# Namespace of your module
@prefix NAME: <http://www.w3.org/2000/10/swap/modulename#> .


# Here your schema.

*****************

A few recommendation about minimal information and how to describe each 
element would be good.


6. TESTING

	- How do I create a test file?
	- Where do I create it?
	- What must be inside?
	- How do I start with a simple case to verify if my test framework 
will be good?
	- When you know that one simple test is working. Create one test. Test 
it. If ok, write the second test. etc. If problems very difficult to 
solve, put your test in comments and continue, and write another one. 
Ask for information about your test on www-archive+n3bugs@w3.org
	- """A good one, with the corner cases you can think of as
well as "normal" cases.""" Tim Berners-Lee
		For example you might want to test things like sin(pi/2) in 
mathematics, which is 1. But might be different because of rounding 
errors.
	- Would be good to have a template.
	- When the test file is created, do "cd test" and do "make"
	- Manual to understand the most common error messages.

7. registration
	- Module has to registered in llyn. For example look at the lines:
	    import cwm_math    # Mathematics
         import cwm_trigo   # Trignometry
	- Why? What is the functionality of llyn? (architecture missing doc)

8. Anything else?


--
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***

Received on Tuesday, 14 October 2003 18:03:01 UTC