Mehrsprachige Quellcode Documentation - Ob & Wie?

[Mavarik]

Zitat von p80286:

a)Kommentare? wer liest die?

Ich habe nicht von Kommentaren gesprochen, sondern von Dokumentation...

Kleines Beispiel aus System.Sysutils

Delphi-Quellcode:

    TMultiWaitEventClass = class of TMultiWaitEvent;
  private
    class procedure FreeAndNil(var Obj); static; inline;
    class function DoWait(const Events: array of TMultiWaitEvent; WaitAll: Boolean; Index: PInteger; Event: PMultiWaitEvent; Timeout: Cardinal): TWaitResult; static;
    function WaiterExpired(var Info: TWaitInfo): Boolean;
    procedure RemoveExpiredWaiters;
  protected class var
    ///  <summary>
    ///    This class variable will be set by a single descendent. The expectation is that one and only one descedent
    ///    of this class exists. That one descendent provides the actual implementation. This class variable is
    ///    used by the static class function Create to construct an instance of that one class that implements the
    ///    needed functionality.
    ///  </summary>
    FMultiEventType: TMultiWaitEventClass;
  protected
    ///  <summary>
    ///    Abstract virtual class overridden in descendant classes to create the proper type for the instance.
    ///  </summary>
    class function CreateInstance: TMultiWaitEvent; virtual; abstract;
    ///  <summary>
    ///    Since This unit doesn't cannot use System.SysUtls, this virtual allows descendants which do have access to
    ///    System.SysUtils to provide a means for this base ancestor class to raise exceptions when validating arguments.
    ///  </summary>
    class procedure ArgumentException; virtual; abstract;
    ///  <summary>
    ///    Since This unit doesn't cannot use System.Classes, this virtual allows descendants which do have access to
    ///    System.Classes to provide a means for this base ancestor to call System.Classes.TThread.GetTickCount.
    ///  </summary>
    class function GetTickCount: Cardinal; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. This explicitly locks this specific instance.
    ///  </summary>
    procedure Lock; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. This explicitly unlocks this specific instance.
    ///  </summary>
    procedure Unlock; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. This must <strong>atomically</strong> set the state of the event.
    ///  </summary>
    procedure AtomicSetEventState(State: Boolean); virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Notifies all current waiters this event is signaled.
    ///  </summary>
    procedure NotifyWaiters; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Clears the storage used for the waiters.
    ///  </summary>
    procedure ClearWaiters; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Add a new waiter to the list of waiters.
    ///  </summary>
    procedure PushWaiter(const Waiter: TWaitInfo); virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Removed a waiter from the list of waiters.
    ///  </summary>
    procedure RemoveWaiter(Index: Integer); virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Returns the current number of waiters in the list of waiters.
    ///  </summary>
    function GetWaiterCount: Integer; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Returns the index'th waiter from the waiter list.
    ///  </summary>
    function GetWaiter(Index: Integer): PWaitInfo; virtual; abstract;
    /// <summary>
    ///    Current number of threads waiting on this event.
    /// </summary>
    property WaiterCount: Integer read GetWaiterCount;
    /// <summary>
    ///    Array of PWaitInfo references which contain information about each waiting thread.
    /// </summary>
    property Waiters[Index: Integer]: PWaitInfo read GetWaiter;
  public
    ///  <summary>
    ///    Rather than use a constructor which will create an instance of <strong>this</strong> class, this will
    ///    return an instance of the registered descendent type that provides the actual implementation.
    ///  </summary>
    class function Create: TMultiWaitEvent; static;
    destructor Destroy; override;

    /// <summary>Wait for this event instance to be signaled or Timeout is reached.</summary>
    function WaitFor(Timeout: Cardinal = INFINITE): TWaitResult; virtual; abstract;
    /// <summary>Explicitly set the event as signaled. This procedure is typically called by the implementation of
    ///    a specific IAsyncResult.
    /// </summary>
    procedure SetEvent;
    /// <summary>Explicitly reset the event as unsignaled. This procedure is rarely if ever called. If it is called, it
    ///    is called by the implementation of a specific IAsyncResult.
    /// </summary>
    procedure ResetEvent;

    /// <summary>Wait until all of the indicated TMultiWaitEvents are signaled or Timeout is reached</summary>
    class function WaitForAll(const Events: array of TMultiWaitEvent; Timeout: Cardinal = INFINITE): TWaitResult; static;
    /// <summary>Wait until at least one of the indicated TMultiWaitEvents are signaled or Timeout is reached</summary>
    class function WaitForAny(const Events: array of TMultiWaitEvent; Timeout: Cardinal = INFINITE): TWaitResult; overload; static;
    /// <summary>Wait until at least one of the indicated TMultiWaitEvents are signaled or Timeout is reached.
    ///   Index out parameter is set to the index of the TMultiWaitEvent in the provided array which was signaled.
    ///   More than one event may be signaled; Index only indicates which one caused the function to return. Index is undefined if
    ///   Timeout was reached.
    /// </summary>
    class function WaitForAny(const Events: array of TMultiWaitEvent; out Index: Integer; Timeout: Cardinal = INFINITE): TWaitResult; overload; static;
    /// <summary>Wait until at least one of the indicated TMultiWaitEvents are signaled or Timeout is reached.
    ///    Returns the TMultiWaitEvent instance which was signaled and caused the function to return. Event is
    ///    undefined if Timeout is reached.
    /// </summary>
    class function WaitForAny(const Events: array of TMultiWaitEvent; out Event: TMultiWaitEvent; Timeout: Cardinal = INFINITE): TWaitResult; overload; static;
  end;

Warum macht man die? Damit Du in der IDE sofort die Infos hast.

Oder Schau die Spring4D an... Da ist fast jede Methode beschrieben...