doc

lib/schild.rb

@@ -1,11 +1,39 @@
 require 'schild/version'
 require 'sequel'
 
-# Das Schild Modul, das alle Klassen für die Datenbankanbindung bereitstellt
+##
+# #Schild Basis-Modul
+# Das Schild Modul, das alle Klassen für die Datenbankanbindung bereitstellt.
+# Die zur Verfügung gestellten Klassen entsprechen dabei den Schild-Tabellen,
+# und den damit verbundenen Assoaziationen.
+#
+# Neben dem Zugriff aus Daten innerhalb einer Tabelle kann über die Schild-Klassen
+# auch auf weitere verknüpfte Tabellen zugegriffen werden. Dazu ein Beispiel:
+#
+# ```ruby
+# Schueler[0].name
+# => "Olsen"
+#
+# Schueler[0].abschnitte[0].jahr
+# => 2017
+# ```
+#
+# Im ersten Beispiel wurde auf den ersten Schüler in der Datenbank ([0]) zugegriffen,
+# und der `name` ausgelesen.
+#
+# Im zweiten Beispiel wird auf den gleichen Schüler zugegriffen und dessen Abschnitt-Tabelle
+# ebenfalls abgefragt. D.h. es wird bereits auf die Abschnitte-Tabelle zugegriffen
+# und automatisch nur Abschnitte zurückgegeben, die zum Schüler gehören. Aus
+# dieser Menge wird ebenfalls der erste Abschnitt gewählt ([0]).
+#
+# Auf diesem Weg können beliebig verschachtelte Anfragen gestartet werden.
+#
+# Es wird empfohlen statt Schild das Modul SchildErweitert einzubinden. Weitere
+# Erläuterungen dazu weiter im Modul.
 module Schild
   Sequel::Model.plugin :tactical_eager_loading
 
-  # @db ist die Datenbank-Verbindung. Alle Daten können über diese Konstante abgerufen werden
+  # @db ist die Datenbank-Verbindung. Alle Daten können über diese Variable abgerufen werden
 
   @db = Sequel.connect("#{ENV['S_ADAPTER']}://#{ENV['S_HOST']}/#{ENV['S_DB']}?user=#{ENV['S_USER']}&password=#{ENV['S_PASSWORD']}&zeroDateTimeBehavior=convertToNull")
   begin
@@ -21,124 +49,161 @@ module Schild
   @db.extension(:freeze_datasets)
   @db.extension(:connection_validator)
 
-  def self.connect
-    @db = Sequel.connect("#{ENV['S_ADAPTER']}://#{ENV['S_HOST']}/#{ENV['S_DB']}?user=#{ENV['S_USER']}&password=#{ENV['S_PASSWORD']}&zeroDateTimeBehavior=convertToNull")
-  end
-
-  def self.db
-    @db
-  end
-
   # Stellt die Schüler-Tabelle samt Assoziationen bereit.
+  # Tabellenname: schueler
   class Schueler < Sequel::Model(:schueler)
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
     many_to_one :fachklasse, :class => :Fachklasse, :key => :Fachklasse_ID
+    # @!method abschnitte
+    # @return [Array<Abschnitt>]
     one_to_many :abschnitte, :class => :Abschnitt
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
     one_to_one :bk_abschluss, :class => :BKAbschluss
-    one_to_many :bk_abschluss_leistungen, :class => :BKAbschlussFaecher
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
+    one_to_many :bk_abschluss_leistungen, :class => :BKAbschlussFach
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
     one_to_one :abi_abschluss, :class => :AbiAbschluss
-    one_to_many :abi_abschluss_leistungen, :class => :AbiAbschlussFaecher
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
+    one_to_many :abi_abschluss_leistungen, :class => :AbiAbschlussFach
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
     one_to_one :fhr_abschluss, :class => :FHRAbschluss
-    one_to_many :fhr_abschluss_leistungen, :class => :FHRAbschlussFaecher
-    one_to_many :vermerke, :class => :Vermerke
-    one_to_one :schuelerfoto, :class => :Schuelerfotos
-    one_to_many :sprachenfolge, :class => :Sprachenfolge
-  end
-
-  # Dient als Assoziation für Schüler und deren Klassenbezeichnung etc.
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
+    one_to_many :fhr_abschluss_leistungen, :class => :FHRAbschlussFach
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
+    one_to_many :vermerke, :class => :Vermerk
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
+    one_to_one :schuelerfoto, :class => :Schuelerfoto
+    # @!method fachklasse
+    # @return [Array<Fachklasse>]
+    one_to_many :sprachenfolgen, :class => :Sprachenfolge
+  end
+
+  # Informationen zu Klassenbezeichnung und weiteren Daten über die jeweiligen
+  # Bildungsgänge. Verfügbar als Assoziationen für Schüler.
+  # Tabellenname: eigeneschule_fachklassen
   class Fachklasse < Sequel::Model(:eigeneschule_fachklassen)
     one_to_many :schueler
   end
 
+  # Versetzungstabelle für Fachklassen. D.h. Klassenbezeichnungen für vorhergehende
+  # und nachfolgende Klassen.
+  # Tabellenname: versetzung
   class Versetzung < Sequel::Model(:versetzung)
     many_to_one :fachklasse, :class => :Fachklasse
   end
 
   # Assoziation für Lehrer, hauptsächlich für Klassenlehrer
+  # Tabellenname: k_lehrer
   class Klassenlehrer < Sequel::Model(:k_lehrer)
     one_to_one :abschnitt, :primary_key=>:Kuerzel, :key=>:KlassenLehrer
   end
 
   # Ist die Assoziation, die Halbjahre, sog. Abschnitte zurückgibt.
+  # Tabellenname: schuelerlernabschnittsdaten
   class Abschnitt < Sequel::Model(:schuelerlernabschnittsdaten)
     many_to_one :schueler, :class => :Schueler, :key => :Schueler_ID
-    one_to_many :noten, :class => :Noten
+    one_to_many :noten, :class => :Note
     many_to_one :klassenlehrer, :class => :Klassenlehrer, :primary_key=>:Kuerzel, :key=>:KlassenLehrer
     many_to_one :fachklasse, :class => :Fachklasse, :key => :Fachklasse_ID
   end
 
   # Assoziation für Noten
-  class Noten < Sequel::Model(:schuelerleistungsdaten)
+  # Tabellenname: schuelerleistungsdaten
+  class Note < Sequel::Model(:schuelerleistungsdaten)
     many_to_one :abschnitt, :class => :Abschnitt, :key => :Abschnitt_ID
     many_to_one :fach, :class => :Faecher, :key => :Fach_ID
   end
 
   # Assoziation für Fächer
+  # Tabellenname: eigeneschule_faecher
   class Faecher < Sequel::Model(:eigeneschule_faecher)
     #siehe abi_...
-    one_to_one :noten
+    one_to_one :note
     one_to_many :abi_abschluss_leistungen
     one_to_one :sprachenfolge, :class => :Sprachenfolge, :key => :Fach_ID
     one_to_many :gliederungen, :class => :Fach_Gliederung, :key => :Fach_ID
   end
 
   # Assoziation für BK-Abschluss des Schülers
+  # Tabellenname: schuelerbkabschluss
   class BKAbschluss < Sequel::Model(:schuelerbkabschluss)
     one_to_one :schueler
   end
 
   # Assoziation für die Prüfungsfächer des Schülers
-  class BKAbschlussFaecher < Sequel::Model(:schuelerbkfaecher)
+  # Tabellenname: schuelerbkfaecher
+  class BKAbschlussFach < Sequel::Model(:schuelerbkfaecher)
     many_to_one :schueler
   end
 
   # Assoziation für Abi-Abschluss des Schülers
+  # Tabellenname: schuelerabitur
   class AbiAbschluss < Sequel::Model(:schuelerabitur)
     one_to_one :schueler
   end
 
   # Assoziation für die Abifächer des Schülers
-  class AbiAbschlussFaecher < Sequel::Model(:schuelerabifaecher)
+  # Tabellenname: schuelerabifaecher
+  class AbiAbschlussFach < Sequel::Model(:schuelerabifaecher)
     many_to_one :schueler
     many_to_one :fach, :class => :Faecher, :key => :Fach_ID
   end
 
   # Assoziation für FHR-Abschluss des Schülers
+  # Tabellenname: schuelerfhr
   class FHRAbschluss < Sequel::Model(:schuelerfhr)
     one_to_one :schueler
   end
 
   # Assoziation für die FHR-fächer des Schülers
-  class FHRAbschlussFaecher < Sequel::Model(:schuelerfhrfaecher)
+  # Tabellenname: schuelerfhrfaecher
+  class FHRAbschlussFach < Sequel::Model(:schuelerfhrfaecher)
     many_to_one :schueler
     many_to_one :fach, :class => :Faecher, :key => :Fach_ID
   end
 
   # Assoziation für die bisher erreichten Sprachniveaus
+  # Tabellenname: schuelersprachenfolge
   class Sprachenfolge < Sequel::Model(:schuelersprachenfolge)
     many_to_one :fach, :class => :Faecher, :key => :Fach_ID
   end
 
-  # Assoziation für die bisher erreichten Sprachniveaus
+  # Besondere Facheinstellungen nach Fachklasse. Betrifft v.a. Sortierung,
+  # Festlegungen über Prüfungsfächer etc.
+  # Tabellenname: fach_gliederungen
   class Fach_Gliederung < Sequel::Model(:fach_gliederungen)
     many_to_one :fach, :class => :Faecher, :key => :Fach_ID
     many_to_one :fachklasse, :class => :Fachklasse, :key => :Fachklasse_ID
   end
 
   # Vermerke von Schülern
+  # Tabellenname: schuelervermerke
   class Vermerke < Sequel::Model(:schuelervermerke)
-    many_to_one :Schueler
+    many_to_one :schueler
   end
 
   # Schülerfotos als jpg
-  class Schuelerfotos < Sequel::Model(:schuelerfotos)
+  # Tabellenname: schuelerfotos
+  class Schuelerfoto < Sequel::Model(:schuelerfotos)
     one_to_one :schueler
   end
 
   # Schul-Tabelle
+  # Tabellenname: eigeneschule
   class Schule < Sequel::Model(:eigeneschule)
   end
 
   # Tabelle für Schild-Nutzer
+  # Tabellenname: users
   class Nutzer < Sequel::Model(:users)
   end
 end
@@ -176,8 +241,9 @@ module SchildErweitert
     Symbol.include SchildErweitert::CoreExtensions::Symbol
     String.include CoreExtensions::String
 
-    # bei include wird für jede Spalte in der Schild-Tabelle eine Ersatzmethode
+    # es wird für jede Spalte in der Schild-Tabelle eine Ersatzmethode
     # erstellt, die bei nil ein Null-Objekt erstellt.
+    # Dazu wird die neu angelegte Methode per MethodLogger gesichert.
     def self.included(klass)
       klass.columns.each do |column|
         name = column.snake_case
@@ -196,6 +262,7 @@ module SchildErweitert
       end
     end
 
+    # Es wird ein Null-Objekt erstellt, das einen Standardwert zurückgibt.
     def create_null_object(klass, column)
       k = Schild.db.schema_type_class(klass.db_schema[column][:type])
       if k.class == Array
@@ -219,11 +286,14 @@ module SchildErweitert
     class Methods
       @@accessor_methods = {}
 
+      # Eine Methode dem MethodLogger hinzufügen
+      # @param klasse, methode
       def self.add(klass, meth)
         @@accessor_methods[klass] ||= []
         @@accessor_methods[klass] << meth
       end
 
+      # Liste von Methoden für eine Klasse auslesen
       def self.list(klass)
         @@accessor_methods[klass]
       end
@@ -237,11 +307,13 @@ module SchildErweitert
     # oder auch andersherum: note.index("4-") => 5
     @note = %w[6 5- 5 5+ 4- 4 4+ 3- 3 3+ 2- 2 2+ 1- 1 1+]
 
+    # @param note [Integer]
     def self.punkte_aus_note(note)
       return if note.nil?
       @note.index(note)
     end
 
+    # @param punkte [Integer]
     def self.note_aus_punkten(punkte)
       return unless punkte && punkte.to_i.between?(1,15) || punkte == "0"
       return punkte if ((punkte.to_i == 0) && (punkte.size > 1))
@@ -250,6 +322,7 @@ module SchildErweitert
     end
 
     # Notenbezeichnung als String
+    # @param ziffer [String]
     def note_s(ziffer)
       case ziffer
       when "1", "1+", "1-"
@@ -413,7 +486,7 @@ module SchildErweitert
   end
 
   # Assoziation für Noten
-  class Noten
+  class Note
     include NotenHelfer
 
     # note in String umwandeln
@@ -452,7 +525,7 @@ module SchildErweitert
   end
 
   # Assoziation für die jeweiligen BK-Prüfungsfächer
-  class BKAbschlussFaecher
+  class BKAbschlussFach
     include NotenHelfer
 
     # Wurde das Fach schriftlich geprüft?
@@ -465,6 +538,9 @@ module SchildErweitert
       self.MdlPruefung == "+"
     end
 
+    # holt die jeweilige Note aus der Tabelle.
+    # Standard ist note_abschluss_ba, als Argument kann auch eine andere
+    # verwendet werden (siehe Tabelle)
     def note(notenart=:note_abschluss_ba)
       note_s send(notenart)
     end
@@ -484,36 +560,42 @@ module SchildErweitert
     end
     alias_method :pruefung_bestanden?, :bestanden_abi?
 
+    # Latinum gemacht?
     def latinum?
       self.Latinum == "+"
     end
 
+    # Kleines Latinum erreicht?
     def kl_latinum?
       self.KlLatinum == "+"
     end
 
+    # Gräcum erreicht?
     def graecum?
       self.Graecum == "+"
     end
 
+    # Hebraicum erreicht?
     def hebraicum?
       self.Hebraicum == "+"
     end
   end
 
   # Assoziation für die jeweiligen Abi-Prüfungsfächer
-  class AbiAbschlussFaecher
+  class AbiAbschlussFach
     include NotenHelfer
 
+    # Note aus Tebelle abfragen, Notenart angeben (siehe Tabelle)
     def note(notenart)
       note_s send(notenart)
     end
   end
 
   # Assoziation für die jeweiligen FHR-Prüfungsfächer
-  class FHRAbschlussFaecher
+  class FHRAbschlussFach
     include NotenHelfer
 
+    # Note aus Tebelle abfragen, Notenart angeben (siehe Tabelle)
     def note(notenart)
       note_s send(notenart)
     end