Re: XML-kommentierung erweitern

Hallo Frank!

"Frank Dzaebel" <Post@xxxxxxxxxxxxxx> schrieb:
Aber soweit ich den OP verstehe, möchte er,
daß nach Eingabe von '///' vor einer Klasse folgender Code eingefügt wird: ... <author>

Falls das der eigentliche Wunsch wäre
wäre das zunächst gegen die C# Spezifikation.
Die ist festgeschrieben.

XML-Kommentare sind nicht Teil der normativen Sprachspezifikation von C#, sondern sie werden im nicht-normativen "Annex E. Documentation Comments" beschrieben.

Zitate aus "Standard ECMA-334: C# Language Specification", 4th edition (June 2006), <URL:http://www.ecma-international.org/publications/standards/Ecma-334.htm>:

S. 487:

| A conforming C# compiler is not required to check the syntax
| of documentation comments; such comments are simply ordinary
| comments. [...]
|
| This specification suggests a set of standard tags to be used in
| documentation comments.

S. 488:

| Although developers are free to create their own set of tags, a
| recommended set is defined in §E.2. [...]
|
| [...]
|
| The documentation generator must accept and process any tag that
| is valid according to the rules of XML. The following tags provide
| commonly used functionality in user documentation. (Of course,
| other tags are possible.)

Nein, das gehört IMHO wenn, dann eher
in die darunter liegende XML-Schnittstelle
(also nach der doc-xml-Erstellung).

Ich stimme soweit zu, als daß ich XML-Kommentare direkt im Quellcode für eine Unart halte, da sie den Quellcode aufblähen und dadurch die Wartbarkeit verringern (insbesondere dann, wenn mehrere Sprachen im Spiel sind). XML ist schließlich eher maschinenlesbarkeit optimiert und weniger auf Lesen/Schreiben durch den Menschen.

--
M S Herfried K. Wagner
M V P <URL:http://dotnet.mvps.org/>
V B <URL:http://dotnet.mvps.org/dotnet/faqs/>

.

Relevant Pages

  • Re: [Tk] Docummentation for Events
    ... I don't mean the basic documentation about Tk events. ... passed thru %tags and may be bound to the handler. ... of the mouse pointer relative to the receiving window. ... in context M, thing B in context N and thing C in context T. ...
    (comp.lang.tcl)
  • Re: HTML Parser
    ... So I did read some documentation on cpan. ... I suppose after you removed the tags there is nothing left to help you ... example for how to extract the body of a element. ... Here we start by setting up a start handler. ...
    (comp.lang.perl.misc)
  • Re: Q: Solutions for requirements tracing (to design, code, and test items)
    ... This is the way translation tools like PathMATE handle documentation. ... If you are doing UML models for the design, most drawing tools allow the application of such tags to model elements fairly painlessly. ... Now that OMG is standardizing tools through MDA, most UML drawing tools offer an XMI or equivalent access to the tool repository to extract the tags and their association with model elements. ...
    (comp.object)
  • Re: XML tags and /doc switch
    ... If I enable this for a single project, add some tags for most objects, ... complaining because you've stated you want documentation, ... So mark classes that you don't intend to be ... The XML file is cool, but I do not see it as ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: Infinite Loops and Explicit Exits
    ... PL> The code can be clear as a bell, properly structured, meaningful data ... That's the kind of comment I had in mind as the necessary comments. ... And I was thinking of the part of documentation which is the ... "Es sind nicht die Generäle und Könige, die die Geschichte machen, ...
    (comp.lang.cobol)