Origional Question:

------------------------------------

Is there a reason that Microsoft left out the ability to put

descriptions on individual parameters of a web service/method? After

all, you can put a description on the class and its constituent web

methods, but why not params? I understand you can put enumerate the

descriptions of params in the method description, but this can be bulky

when you're dealing with a large number of them, and it doesn't seem

highly efficient. Any plans to remedy this in Beta 2?



ScottGu Answer:

-------------------------------------



Hi Daniel,



I just talked with the guy who owns this feature.  According to him, the

description properties on the webservice and webmethod attributes are

really only intended for small descriptons -- not as a general

documentation technique.  The best practice we are recommending is to

create detailed documentation for the service, and then link to it from

the description field. 



Apparently TerraServer is a good example of someone doing this and can

be found at: <http://terraserver.microsoft.net/default.aspx>



Hope this helps,



Scott

Thanks for the answer Scott.  However, how would this linking method work

 when someone is viewing the WSDL contract for a web service?  After all,

 putting the description in the web service file seems like it would ensu

re the information being available when someone browses to either the web

 service .asmx file or to the WSDL.







-------Original Message-------



From: Scott Guthrie <scottgu@m...>

Date: Thursday, March 22, 2001 02:26:56 PM

To: ASP+ <aspx@p...>

Subject: [aspx] WebMethod Documentation Question Answered



Origional Question:

------------------------------------

Is there a reason that Microsoft left out the ability to put

descriptions on individual parameters of a web service/method? After

all, you can put a description on the class and its constituent web

methods, but why not params? I understand you can put enumerate the

descriptions of params in the method description, but this can be bulky

when you're dealing with a large number of them, and it doesn't seem

highly efficient. Any plans to remedy this in Beta 2?



ScottGu Answer:

-------------------------------------



Hi Daniel,



I just talked with the guy who owns this feature. According to him, the

description properties on the webservice and webmethod attributes are

really only intended for small descriptons -- not as a general

documentation technique. The best practice we are recommending is to

create detailed documentation for the service, and then link to it from

the description field.



Apparently TerraServer is a good example of someone doing this and can

be found at: <http://terraserver.microsoft.net/default.aspx>



Hope this helps,



Scott

I think that ASP.NET Beta 1 has enough support for documentation of Web 

Services in the asmx file itself or provide a link to another aspx/html 

page giving all the help in the world. The Description Attribute takes 

long enough strings as argument and you can also use HTML formatted 

strings and link the required Help pages.



Take a look at the following sample code:



(Just copy and paste the following code same it as FooService.asmx and 

call it through IIS)



<%@ WebService Language=3D"C#" Class=3D"FooService" %>

// FooService.asmx



using System;

using System.Web.Services;



[WebService (Description =3D "This service provides String 'Bar' and 

Strin 'Foo' at the askance. Click <a 

href=3D'doc/ServiceDescription.aspx'>here</a> for further information on 

this service")]

public class FooService : System.Web.Services.WebService

{



[WebMethod (Description=3D"Takes your name as input and emits a message 

to you. For a more detailed description of this method and its parameter 

click <A href=3D 'doc/FooMethodDescription.aspx'>here</a> ")]



public String Foo(String YourName)

{

  return (YourName + "! Foo!!");

}

}



Prasad DV

[ I am a Chartered Accountant based at Salem, India who is planning to 

migrate into a career in Web Technologies and .NET and welcomes good 

offers]



Reply to

Message #2 by "Daniel Anderson" <dcanderson@u...> on Thu, 22 Mar 2001 

17:54:17 -0700 (Mountain Standard Time)



Daniel Wrote:

Thanks for the answer Scott.  However, how would this linking method 

work=3D

 when someone is viewing the WSDL contract for a web service?  After 

all,=3D

 putting the description in the web service file seems like it would 

ensu=3D

re the information being available when someone browses to either the 

web=3D

 service .asmx file or to the WSDL.