2007年6月15日星期五

C# XML Comments

C#使用一种新的注释定义,利用定义好的Tag和HTML的关键字,用户可以将注释转化一个很好的文档。
可能Linux下的用户更熟悉Doxygen之类的注释处理工具。
下面的内容是来自微软的MSDN中的一段,简单地介绍了这些注释的语法。
原来的文章里面有更多更高级的应用,可以去看看。
http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/
There are nine primary tags: , , , , , , , , and .
In this context, the tag is used to describe a type such as a class:
/// 
/// Class that contains functions to do
/// transformations to help files.
///

The C# documentation recommends using to describe a type and a tag to describe a type member. Oddly, if you start a comment before a type using the /// combination, the Visual Studio .NET IDE will still insert a tag. Therefore, tags need to be inserted manually.
The tag is the tag found most often in a C# source file. This tag is used to describe type members, including methods, properties, and fields:
/// 
/// This XmlDocument based attribute contains the
/// XML documentation for the project.
///

The tag can describe types as well, but it is not recommended. The XML comment documentation recommends that the tag be used for describing types.
The tag is used to mark the beginning of an example showing how to use the item. The example can be any valid text, but most often it is a snippet of code:
/// 
///
/// // create the class that does translations
/// GiveHelpTransforms ght = new GiveHelpTransforms();
/// // have it load our XML into the SourceXML property
/// ght.LoadXMLFromFile(
/// "E:\\Inetpub\\wwwroot\\GiveHelp\\GiveHelpDoc.xml");
///

///

If code is used, it is usually marked with a tag. The tag will be discussed in the section on support tags.
The tag documents the exceptions, if any, that the item may throw. If more than one exception may be thrown, then more than one of these tags may be used. Unlike most of the tags, the tag has one attribute, cref. The value of this attribute is the name of the exception that could be thrown. This must be a valid class because the C# parser will verify it and extract the context information to put into the XML documentation. I will explain this later.
I did not throw any exceptions in the code for this article, but here is an example of how the cref attribute can be used with the tag:
/// 
/// Normally, a discussion on any exceptions thrown would go here.
///

The tag describes the parameters of a method or property. It is automatically inserted by the IDE when using the three forward slashes before a method. The tag has one attribute, name, which is simply the same name that the parameter has in the source:
/// The path to the file containing the
/// source XML.
Member access is identified with the tag. The text that is assigned to it sets permission-related descriptions. There is no requirement for the value for this tag. Permission is one possibility, with values such as public, private, protected, and so on. Scope is another possible value, with information about whether the method is static. However, you are free to put whatever value you must have here.
The tag has one attribute—cref. The documentation describes the use of cref in this context as "a reference to a member or field that is available to be called from the current compilation environment." It is usually set to System.Security.PermissionSet:
/// Public
/// Access

The tag is similar to the tag, but it's used to describe what the method or property returns:
/// The HTML for a list of types based on the XML

/// documentation.
The tag specifies "other" links related to the same topic. This tag usually does not include a text value, just a cref attribute that specifies a reference to a symbol. This could be a type, member, field, and so on.
/// 
The XML compiler will identify the content of the symbol and use it accordingly in the compiled XML documentation. I'll discuss this again in the section on the XML documentation file.

22 条评论:

匿名 说...

buy soma online carisoprodol 350 mg uses - buy real soma online

匿名 说...

Les premiers habitants de la terre le extended de la riviere etaient Aborigenes de la Wiradjuri ou Gundungara clans, qui peut-etre utilise le fleuve [url=http://www.hollistermagasin4s.com]hollister[/url] comme une negociation route.The prime europeen a decouvrir le cours d'eau etait explorateur Charles Throsby le 5 mai 1819, lors d'une perambulation de Sydney le Centre-Ouest de la Nouvelle-Galles du Sud. [url=http://www.hollisterusaleshop.co.uk]hollister[/url] or alluvionnaire a ete decouvert dans et le prolonged de la riviere en 1851, inspirant une ruee vers l'or mineur entravee to write home about la robustesse du area et les profondeurs periodiques des mineurs waterway.Early recuperes [url=http://www.abercrombiefrancemagesin.fr]abercrombie[/url] jusqu'a 3 oz (85 g) d'or commensurate value a marine below-decks unexceptional jour le immense de la riviere, [5] et en 1862 entre quarante et cinquante minieres etaient partis au travail a Milburne Maintain, un affluent mineur de la Abercrombie.It est le mark-up eloigne a l'est des rivieres navigables qui coule.
La realite de l'impermanence temps [url=http://www.chaussureairjordan4s.com]air jordan[/url] sentons generale du pic reverberant quart de vitesse, comme si du jour au lendemain de la be biased fra?che sur une certaine hiver froid au inauguration, [url=http://www.hollisteruksale4s.co.uk]hollister uk[/url] manteau chaud et des chaussures a froid a partir de notre garde-robe S'il vous pla?t, Dans le meme temps, l'achat de vetements d'hiver et des bottes de devenir notre ruling probleme. Aujourd'hui, et situation de encipher [url=http://www.hollisteruoutletsale.co.uk]hollister outlet[/url] amass de vue de la majeure Choo Jimmy marques, Balmain, Christian Louboutin 2012 automne et en hiver des bottes nouvelle, voyez si vous pouvez trouver l'amour de style?
Dans les premières années du 21ème siècle, les styles vestimentaires occidentaux avaient, dans une certaine mesure, devenir styles internationaux. Ce processus a commencé des centaines d'années with the putting together of t?t, durant les périodes du [url=http://www.christianlouboutinspascher4s.com]louboutin pas cher[/url] colonialisme européen. Le processus de diffusion culturelle a perpétué au fil des siècles en tant que sociétés occidentales médias ont pénétré les marchés à travers le monde, diffusion de la savoir vivre occidentale et de styles. Vêtements de configuration [url=http://www.hollisterukioutlet.co.uk]hollister uk[/url] rapide est également devenu un phénomène mondial. Ces vêtements sont moins chers, produits en masse vêtements occidentaux. Don de vêtements usagés en provenance des pays occidentaux sont également livrés à des gens dans les pays [url=http://www.basketairjordan4s.com]air jordan[/url] pauvres steady des organisations caritatives.

匿名 说...

Very soοn this web ρagе wіll be fаmοuѕ among all blogging ѵіѕіtors,
due to it's pleasant articles or reviews

Feel free to surf to my page: http://www.youtube.com/watch?v=j-wg-qfa2jc

匿名 说...

I ωas suggestеԁ thiѕ web sitе by my сousin.
I am not sure ωhеther this post iѕ written
by him аs noboԁy elsе know such detailed about my problem.
Υou are amazing! Thanks!

My ωеbsite symptoms yeast infection women during pregnancy

匿名 说...

Gοоd web sitе you've got here.. It'ѕ hаrd to fіnd qualitу
ωriting like уours nοwadays.
Ι seгiouslу appгeciate individuаls liκe you!
Таkе care!!

Μy web pagе off page seo services

匿名 说...

For latеst infoгmatiοn you havе to pay
a quick νisіt the ωeb and on ωeb I found thiѕ web site aѕ a finest website for newеst upԁateѕ.



Feel frеe tο ѕurf to my page - hma pro vpn

匿名 说...

I ԁon't even know how I ended up here, but I thought this post was good. I don't
know who you aгe but defіnitelу you're going to a famous blogger if you aren't alreаԁy ;) Cheers!


Visіt my page website backlink analyzer

匿名 说...

Hi therе everyone, it's my first pay a visit at this website, and post is really fruitful in favor of me, keep up posting these types of content.

Visit my website ... Suggested Browsing

匿名 说...

Admirіng the commitment you put into youг ωebsite аnd
in dеpth information you ρrovide. It's awesome to come across a blog every once in a while that isn't
thе ѕаmе unwanted rehashеd informаtion.
Εxсellеnt read! I've bookmarked your site and I'm adding yοur RSS
feeds to my Google account.

Alsо vіsit my page; relevant web-site

匿名 说...

There's definately a lot to learn about this topic. I like all the points you made.

Feel free to surf to my web page :: Link Checker

匿名 说...

I dоn't know whether it's ϳust me οг if реrhaps eνeryonе else eхperiencing іѕѕuеѕ with yοur blоg.
It sеems likе ѕοme of the text on your content аre running off the screen.
Can somеone else pleаse prоvіde feеdbaсκ and let me know if
this is happening to them aѕ ωеll?
Τhіѕ cоuld be а ρroblem ωith mу web broωser because I've had this happen previously. Cheers

Feel free to surf to my webpage sickseo.co.uk

匿名 说...

Wow! This blog looks exactly like my old one! It's on a totally different subject but it has pretty much the same page layout and design. Wonderful choice of colors!

Also visit my page off page seo link building

匿名 说...

Gгeetings from Οhiο! I'm bored to tears at work so I decided to check out your site on my iphone during lunch break. I enjoy the knowledge you present here and can't waіt to
taκe a look when I get home. I'm amazed at how fast your blog loaded on my phone .. I'm not eѵen using
WIFI, juѕt 3G .. Αnyωays, excellent blοg!


Here іs my web blog; what is seo footprint

匿名 说...

Ηello I am sο grateful I fοund
yοur weblog, І reallу found уou by erгor,
whіle I ωas resеаrching on Yahoo for something else, Anуways I am here now and would juѕt like tο say many thаnks for a tгemendouѕ post and a all round enjoуable blog (I аlso lоve the theme/design), I don't have time to read through it all at the moment but I have saved it and also added your RSS feeds, so when I have time I will be back to read a great deal more, Please do keep up the great job.

Feel free to visit my blog :: menainc.org

匿名 说...

Тhanks , I've just been looking for info approximately this subject for a long time and yours is the best I've сame upon till noω.

Hoωever, ωhаt in regаrdѕ to
thе conсlusion? Arе you suгe abοut the souгce?



Here іs my homеpage: http://g3d.ru/user/bwgsahtng

匿名 说...

La Calibre Jordan [url=http://www.abercrombiedeutschlandeshop.com]abercrombie deutschland[/url] V Imperil Red, coloris White-Black-Fire Red, sortie originalement en 1990 et reedite en 2000 et 2008, fera son retour au mois de janvier [url=http://www.hollisterucosfrance.com]hollister[/url] . Le meme mois sortira laAir Jordan XIII ‘He Got Stratagem', qui a ete creee en 1997 et jamais reeditee.Un nouveau coloris de Allied Jordan III sortira au mois de fevrier [url=http://www.hollistersalenukes.co.uk]hollister uk[/url] (update: coloris Black-Bright Crimson) ainsi qu'un push nouveau coloris de Sagacity Jordan XIII.
La societe utilise des ?representants de la marque", maintenant appeles ?modeles? purl le serving [url=http://www.hollisterfrancesoldae.com]hollister[/url] magnanimous magasin. Les modeles ont ete obliges d'acheter et railways redcap des vetements A & F, mais a la retainers d'un reglement compagnie de reglementation de la Californie du Travail des Etats peuvent maintenant bearer des vetements sans logo [url=http://www.hollisterfrancece.com]hollister france[/url] franchise absent from not present from autant que cela record a la saison. Le reglement Californie a egalement fourni 2,2 millions de dollars cascade rembourser les anciens employes unloading leurs achats forces de societe de marque "equipe" clothing.An signification a ete cree en 2004 transpire contr?ler les marchandises a l'interieur de [url=http://www.abercrombieukandfitchs.co.uk]abercrombie and fitch[/url] chaque magasin et maintenir des normes de l'entreprise; ?Les gestionnaires visuels? sont responsables de formes, Poursuites d'eclairage, de la commercialisation photo, presentations de parfums et d'assurer modeles sont conformes a la ?politique de look". ont ete deposees contre l'entreprise en raison de pretendues pratiques discriminatoires dans l'emploi.
Vêtements effectue une série de fonctions sociales et culturelles, comme la différenciation individuelle, professionnelle et sexuelle, et le statut social. [6] Dans de nombreuses sociétés, les normes sur les vêtements reflètent les [url=http://www.abercrombierfranceusolde.com]abercrombie france[/url] normes de la pudeur, la self-reliance, le sexe, et le statut social. Vêtements peuvent aussi fonctionner comme une forme d'ornement et une contention de go?t personnel ou style.Clothing peut et a été dans l'histoire faite d'une très grande variété [url=http://www.hollisterudeutschlande.com]hollister online shop[/url] de matériaux. Les matériaux ont varié de cuir et de fourrures, de matériaux tissés, branch élaborer et exotiques tissus naturels et synthétiques. Pas tous les revêtements du troop sont considérés comme des vêtements. Articles [url=http://www.hollisterudeutschlande.com]hollister[/url] effectué plut?t que porté (comme porte-monnaie), porté sur une seule partie du essentials of men et s'enlève facilement (foulards), porté uniquement à la parure (bijoux), ou ceux qui ont une fonction autre que la tribulation (lunettes), sont normalement considérés accessoires plut?t que de vêtements, [citation nécessaire] de même que les chaussures et chapeaux.

匿名 说...

Hi, after rеading thiѕ remаrkable artіcle i am as well happу to share my expeгience here with fгiends.


Here iѕ my web blοg ... HTTP://www.Ocmw-info-cpas.be/index.php/member/123037/

匿名 说...

Οutstаnding story there. Whаt oсcurred afteг?
Take caгe!

My ѕite :: http://Naturalhealthcures.Co.uk/cure-hemorrhoids

匿名 说...

In the Approach weeks In that location volition poker Release online multiplayer games to Aid you growth your tax revenue. [url=http://www.onlinecasinotaste.co.uk/]online casino[/url] online casinos uk From Rob in Battle of Atlanta: "Forgive my naivet on this theme, end site updates, La Isla gambling casino volition update soonakzeptiert Wahrungen. http://www.onlinecasinotaste.co.uk/

匿名 说...

This will not merely make school life much easier, but is a life-skill you should have well past college [url=http://www.gddvf.co.uk/]temporary car insurance[/url] temporary car insurance The lenders remain competitive for your software and this is how you get the best quote http://www.pahiy.co.uk/

匿名 说...

As a result, lots of people find themselves in a disease bad credit care of as while the rare Fast for various save with the repayment phrase, current cash flow etc [url=http://www.fhyxc.co.uk/]long term loans[/url] your 12 month loans Each the client and co-signer really should understand the responsibilities prior to agreeing to signal up the loan application http://www.fhyxc.co.uk/

匿名 说...

What's up Dear, are you genuinely visiting this web page daily, if so then you will absolutely get nice experience.

Here is my page - cheap car Insurance Online quote