[nem-pl] Dokumentacja w kodzie

[Michal Moskal]

On Sun, Nov 23, 2003 at 02:54:09PM +0100, "Paweł W. Olszta" wrote:
> 
> Hej,
> 
> ponieważ do tej pory nie ustaliliśmy, jak ma wyglądać dokumentacja w 
> źródłach, proponuję
> póki co używać standardu Visual Studio .NET.
> 
> http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfTagsForDocumentationComments.asp?frame=true
> http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vcoriXMLDocumentation.asp
> http://msdn.microsoft.com/msdnmag/issues/02/06/xmlc/default.aspx
> 
> Michał napisał już skrypt, który wycina odpowiednie komentarze. Trzeba 
> będzie jakiegoś
> stylesheeta jeszcze zrobić.

IMHO:

1. <summary> jest zbędne. To co jest na początku magicznego komentarza
   bez taga, to summary. Pozwoli to uprościć przypadki typu:

      (** Frabnicate the output. *)
      foo () : void { ... }

   Zamiast:

      (** <summary>Frobnicate the output.</summary> *)
      foo () : void { ... }

   Nie sądzę, żeby komuś się chciało pisać <parm> i inne takie dla
   każdej funkcji, chyba, że w jakiś super publicznych interfejsach.

2. [...] jako skrót dla <c>...</c>.

3. <p> zamiast <para>

Nie rozumiem czemu dla properties jest <value> a nie <summary>.

Reszta wydaje się w miarę sensowana.

-- 
: Michal Moskal :: http://www.kernel.pl/~malekith : GCS {C,UL}++++$ a? !tv
: When in doubt, use brute force. -- Ken Thompson : {E-,w}-- {b++,e}>+++ h