Forum OpenACS Development: Re: Tcl Web Services Toolkit: TWiST
with regards to the wsdb documentation I would love to see both documentation for types and operations. But to my understanding the standard WSDL 1.1 only supports the documentation tag in the operation, not in the type defininition. If I am wrong, then please find a way to describe the types, this does make much more sense (as you noted).
How could the WSDB documentation be represented: In general I would have the WSDB be enhanced by documentation fields, so the inspect functions could display the documentation as well. Here having additional commands for the documentation might be a good thing.
When displaying the webservice itself (using ?WSDL or your internal display method) the generated < documentation > tags can then be viewed when you call your page (w.g. at e4.cognovis.biz/twsdl/projectmanager), which list all the operations, along with the corresponding documentation. Once you click on one operation, you will see all the entry fields along with their documentation. Probably you would have to display what is expected to come back with documentation as well. Not sure how this works.
If using < ws >, I would really not have a separate procedure for the documentation, both for type as well as for proc (and namespace, if that makes sense). Let the < ws > proc handle the dual calls to insert the webservice along with the documenation into the WSDB. Not so sure that having a different command to desribe the documentation afterwards is the way to go, but probably I am just too much an OpenACS guy.
I'm somewhat confused by this. Are the wrapper procs merely to provide documentation for the <ws>* APIs? Looking at the internals of the <ws>* APIs, indicates that the wrapper have to have a similar internal structure, because there are subcommands. Therefore the evolution of the wrapper would have to concern itself with the internals of the wrapped APIs. This same handholding would be required for every other external package. Additionally, this duplicates the documentation effort, even if it is copy/paste, the wrapper API provides nothing new in functionality. But it does provide another layer which must be maintained and debugged and traced through in case of errors.
If using <ws>, I would really not have a separate procedure for the documentation, both for type as well as for proc (and namespace, if that makes sense). Let the <ws>proc handle the dual calls to insert the webservice along with the documenation into the WSDB. Not so sure that having a different command to desribe the documentation afterwards is the way to go, but probably I am just too much an OpenACS guy.
I'm trying to maintain some civility here, but this is somewhat interesting way of looking at things. First a minor issue. The API is written <ws>*, there are no spaces. It is like constantly mispronouncing someone's name, on purpose due to laziness. Second, I'm not interested in how you think it should be done or where the information should be stored (I am interested in _what_ should be documented). Anything like this must first have a corresponding API in tWSDL. If you read my next-to-last post, I included a comment I put in a file when I first wrote TWiST: higher level APIs must use the tWSDL API. The meaning of this is that higher level APIs cannot mess with the internal storage of the WSDB. This forced use of the API helps identify deficiencies in tWSDL as well as hacks which need code cleanup. I have done several rounds of this already in tWSDL and TWiST.
Having a separate documentation API keeps the two functions separate. I can't imagine how it would be possible to not have massive duplication of code if every <ws>* API had to have its own documentation handler. I have already outlined the deficiencies with the ad_proc method. First is that I would have to duplicate what ad_proc does. But which ad_proc do I follow? There are several versions, and I doubt that we have seen the last version. Changes in version require redoing previous documentation blocks, or maintaining backwards compatibility. If similar to, but not quite the same as ad_proc, a documentation block will lead to inevitable confusion for those who use ad_proc and expect it to be identical. For those unfamiliar with ad_proc, they must learn how the documentation block works. Finally, <ws>proc does more than define a procedure. It defines simpleTypes, complexTypes, input and output messages and an operation.
But most important, and this is really important: I cannot think of a single use of documentation blocks in API calls. Does anyone call db_multirow with a documentation block? I guess you could call ad_page_contract an example. It is a great example of one procedure doing too many things. I'm sure the code for it is difficult to maintain. But just a clue to my method of API development: I write monolithic procs which contain too much code at first. I get things to work, and then I chop up the internals and produce single function APIs to support the original one. I don't keep adding functions to existing API unless it is 'functionally necessary'. Of course I don't always succeed, but it is a valid criticism for code which needs cleanup. Okay one more thing: documentation is data. I don't know if you can include documentation in the schema of a WSDL, but since the namespace of the schema is the xml schema, the rules are the same as that namespace. But even if the WSDL standard doesn't allow the inclusion of documentation in a particular place, this has no importance with respect to the decision to document, at least internally, particular components. The documentation inside the operation might contain a url to an html document, compiled from more complete internal documentation.
My original comment was that it would be nice if there was an independent OpenACS package which allowed you to access the documentation of an external package as if the APIs were part of OpenACS. For instance: Tcl, AOLserver, tDOM. Does anyone wrap these procs? If you could create a package for AOLserver, then the documentation for TWiST would also show up in the same place. Of course my inspect package shows the current state of the code and variables in that thread, but this is not documentation, it is for debugging and analysis.
In an ideal world I would be able to register all procedures with their names within the API Browser, so that searches for "string" would turn up the commands for the TCL string function, but this is not how the API Browser works *yet*.
Writing a package for OpenACS only makes sense once the API has stabilized though, which holds true for any wrapper functionalities.
I have to correct myself, if someone is interested in a tighter integration between tWSDL / TWiST and OpenACS then write procedures similar to the <ws>* procs in OpenACS "style" which make use of functionalities that only make sense if you have installed OpenACS. We have ample of examples where OpenACS wraps existing external API into it's own functionality blocs, like ad_return* or ad_proc .... So do not write a simple wrapper which does not add any new functionality except documentation, but I guess from my posting it was not obvious that this advantage comes in hand as well 😊.
However, if I were to write a quick 'integration' package for OpenACS, it would import the correct version (for the OpenACS package) from the google code repository. After that import, it can then be packaged up into an .apm file for distribution, or maybe the package would simply do the import upon installation. The package would then provide the TWiST API. The next step would be a wizard type interface which would produce a TWiST configuration file.
