Creating Documentation

Is there a tool in webMethods that can create the documentation akin to javadoc?

I was referring to a tool/utilitythat can help document the user created application packages and flows in webMethods

Right click on the service name in the left-hand pane in Developer. Click on View as HTML.

The comments field on the input/output tab is a good place to put comments. Put the comments in HTML format and they will show up nicely when you do View as HTML.

Thanks Rob

Hmmm… I think what is still missing is a documentation system for how services “fit together”. i.e. we may document each service seperately, but how can we document the execution flow where these services are invoked, one after the other?

I think webMethods can nail down a huge advantage by getting a really good documenation system in place. How can this be done?

Firstly: by auto-generating documentation for all services in the system and storing them in an easily accessible format (quite like javadoc does). Right now, the developer is required generate the document for each service manually.

Second: Intelligently correlate developer comments with the beautiful documentation already being generated. For instance, if the service comments state:
[I]INPUT

a - This is the first input variable
b - This is the second input variable
[/i]
…the documentation parser should ‘pick up’ the comments for the ‘a’ and ‘b’ records and display them against these records in the service input signature in the documentation. Ditto for output.

Third: And this is the most important one - Make it easy to show how service calls chain together. For B2B systems without TN, this can be done quite easily by putting hyperlinks against the service invokes in the documenatation.

It is for systems with Trading Networks where this idea really comes into its own. Here, TN activity logs can be used to autogenerate documentation on the flow of execution.

For example, consider a document “D” that entered Trading Networks. It may be picked up by a processing rule called “Inbound PO Receive”, in which case a log entry:
“Routing rule wfin - Inbound PO Receive selected”
appears in the activity log for that document. This processing rule may execute a webMethods IS service, which could in turn, generate two more documents, and so on. Now, if a special variable (say, the documentID of the initial document) is preserved throughout the flow of execution, the entire execution chain can be traced and automatically documented. All the developer will have to do is go to Transaction Analysis in the Trading Networks Console, right-click a document and select “Autogenerate execution chain”. He does this to a select few documents, and voila! the system is comprehensively documented, including the important execution chains!

Is some from WM listening on this? Please use these suggestions - it’s something sorely missed in WM. Or pay me - I’ll do it myself.

Can’t more agree. I have spent days with documenting data flow in Excel format. We do need a “source code” of our integrations.

Thanks for the suppot Gabor. I’ve done days documenting WM mappings in Excel myself - laborious, wasteful … but unavoidable unless WM implements a better doc system.

I hope WM seriously consider doing this. It’ll save a whole heap of manyears for its customers

I agree that some additions would be quite helpful.

For Sonam’s items:

  1. Generate for all services. This would be great. Either for all services on the server or selectively for a given package. We should be able to create a FLOW service ourselves to do this. Anyone have bandwidth to tackle this?

  2. Intelligent parsing of comments to combine with the generated parameter information. A variation would be to not generate the paramter list if parameter comments are present.

  3. Call tree. This would indeed be cool. I suspect we’ll not see this any time soon. A document/process flow diagram derived from TN activity is probably even less likely–but provides a great opportunity for someone to plug this hole and maybe make some money. I know I’d pay for such a tool (though not if it’s from wM–it should be included).

I’ve seen flow code that documents IS flow based on comments that are input into the flow code. Interesting concept because it walks the nodes, finds comments, determines tree hierarchy and generates “java-doc” like documentation. The secret is to have a lot of comments in your code.

Ray

Ray,

Any ideas on where we can get a sample package.
I think we’re all interested.

Chris

Yeah dude! Don’t entice us like that and then leave us hangin! What is this cool doc generator of which you speak and can we get our hands on it?