fortsetzung doku

lib/schild.rb

@@ -2,7 +2,7 @@ require 'schild/version'
 require 'sequel'
 
 ##
-# #Schild Basis-Modul
+# === 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.
@@ -10,13 +10,11 @@ require 'sequel'
 # 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
-# ```
+#     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.
@@ -28,13 +26,13 @@ require 'sequel'
 #
 # 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.
+# Es wird empfohlen statt Schild das Modul SchildErweitert einzubinden. Es
+# beinhaltet neben den Assoaziationen auch weitere Methoden.
+# 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 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
     retries ||= 0
@@ -49,168 +47,209 @@ module Schild
   @db.extension(:freeze_datasets)
   @db.extension(:connection_validator)
 
-  # Stellt die Schüler-Tabelle samt Assoziationen bereit.
+  # Stellt die Schüler-Tabelle mit Assoziationen bereit.
+  # Die aufgeführten Instanzmethoden sind ausschließlich Assoaziationen.
+  #
   # Tabellenname: schueler
   class Schueler < Sequel::Model(:schueler)
     # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @return [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>]
+    # @!method bk_abschluss
+    # @return [BKAbschluss]
     one_to_one :bk_abschluss, :class => :BKAbschluss
-    # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @!method bk_abschluss_leistungen
+    # @return [Array<BKAbschlussFach>]
     one_to_many :bk_abschluss_leistungen, :class => :BKAbschlussFach
-    # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @!method abi_abschluss
+    # @return [AbiAbschluss]
     one_to_one :abi_abschluss, :class => :AbiAbschluss
-    # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @!method abi_abschluss_leistungen
+    # @return [Array<AbiAbschlussFach>]
     one_to_many :abi_abschluss_leistungen, :class => :AbiAbschlussFach
-    # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @!method fhr_abschluss
+    # @return [FHRAbschluss]
     one_to_one :fhr_abschluss, :class => :FHRAbschluss
-    # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @!method fhr_abschluss_leistungen
+    # @return [Array<FHRAbschlussFach>]
     one_to_many :fhr_abschluss_leistungen, :class => :FHRAbschlussFach
-    # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @!method vermerke
+    # @return [Array<Vermerk>]
     one_to_many :vermerke, :class => :Vermerk
-    # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @!method schuelerfoto
+    # @return [Schuelerfoto]
     one_to_one :schuelerfoto, :class => :Schuelerfoto
-    # @!method fachklasse
-    # @return [Array<Fachklasse>]
+    # @!method sprachenfolgen
+    # @return [Array<Sprachenfolge>]
     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
+    # @!method schueler
+    # @return [Array<Schueler>]
+    one_to_many :schueler, :class => :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
+    # @!method fachklasse
+    # @return [Fachklasse]
+    many_to_one :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 => :Note
-    many_to_one :klassenlehrer, :class => :Klassenlehrer, :primary_key=>:Kuerzel, :key=>:KlassenLehrer
-    many_to_one :fachklasse, :class => :Fachklasse, :key => :Fachklasse_ID
+    # @!method klassenlehrer
+    # @return [Klassenlehrer]
+    many_to_one :klassenlehrer, :primary_key=>:Kuerzel, :key=>:KlassenLehrer, :class=>:Klassenlehrer
   end
 
   # Assoziation für Noten
+  #
   # 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
+    # @!method fach
+    # @return [Fach]
+    many_to_one :fach, :class => :Fach
   end
 
   # Assoziation für Fächer
+  #
   # Tabellenname: eigeneschule_faecher
-  class Faecher < Sequel::Model(:eigeneschule_faecher)
-    #siehe abi_...
+  class Fach < Sequel::Model(:eigeneschule_faecher)
+    # @!method note
+    # @return [Note]
     one_to_one :note
+    # @!method abi_abschluss_leistungen
+    # @return [Array<AbiAbschlussFach>]
     one_to_many :abi_abschluss_leistungen
+    # @!method sprachenfolge
+    # @return [Sprachenfolge]
     one_to_one :sprachenfolge, :class => :Sprachenfolge, :key => :Fach_ID
+    # @!method gliederungen
+    # @return [Array<Fach_Gliederung>]
     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
+  #
   # Tabellenname: schuelerbkfaecher
   class BKAbschlussFach < Sequel::Model(:schuelerbkfaecher)
-    many_to_one :schueler
+    # @!method fach
+    # @return [Fach]
+    many_to_one :fach, :class => :Fach
   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
+  #
   # Tabellenname: schuelerabifaecher
   class AbiAbschlussFach < Sequel::Model(:schuelerabifaecher)
-    many_to_one :schueler
-    many_to_one :fach, :class => :Faecher, :key => :Fach_ID
+    # @!method fach
+    # @return [Fach]
+    many_to_one :fach, :class => :Fach
   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
+  #
   # Tabellenname: schuelerfhrfaecher
   class FHRAbschlussFach < Sequel::Model(:schuelerfhrfaecher)
-    many_to_one :schueler
-    many_to_one :fach, :class => :Faecher, :key => :Fach_ID
+    # @!method fach
+    # @return [Fach]
+    many_to_one :fach, :class => :Fach
   end
 
   # Assoziation für die bisher erreichten Sprachniveaus
+  #
   # Tabellenname: schuelersprachenfolge
   class Sprachenfolge < Sequel::Model(:schuelersprachenfolge)
-    many_to_one :fach, :class => :Faecher, :key => :Fach_ID
+    # @!method fach
+    # @return [Fach]
+    many_to_one :fach, :class => :Fach
   end
 
   # 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
+    # @!method fach
+    # @return [Fach]
+    many_to_one :fach, :class => :Fach
+    # @!method fachklasse
+    # @return [Fachklasse]
     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
+  class Vermerk < Sequel::Model(:schuelervermerke)
   end
 
   # Schülerfotos als jpg
+  #
   # 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
 
+# ==SchildErweitert
+# Dieses Modul bindet das Schild-Modul ein und erweitert es mit zusätzlichen Methoden
+# zum einfachen Zugriff auf Schild-Methoden, die teilweise verschachtelt sind.
+# Ebenso bietet SchildErweitert alle Methoden mit Null-Objekten, d.h. es
+# gibt kein +nil+, nur Standardwerte.
 module SchildErweitert
-  # erst Ruby 2.1.0 macht include zu einer public-Methode
   if Module.private_method_defined? :include
+    # erst Ruby 2.1.0 macht include zu einer public-Methode
     class Module
       public :include
     end
@@ -219,7 +258,12 @@ module SchildErweitert
   # String und Symbol werden um snake_case ergänzt, das die Schild-Tabellen umbenennt
   # Legacy-Methoden aus alten Schild-Versionen wird teilweise auch unterstützt.
   module CoreExtensions
+    # Patch für String
     module String
+      # wandelt Strings in +Snake Case+ um.
+      # Beispiel:
+      #     CamelCase.snake_case
+      #     => camel_case
       def snake_case
         return downcase if match(/\A[A-Z]+\z/)
         gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
@@ -228,7 +272,9 @@ module SchildErweitert
       end
     end
 
+    # Patch für Symbol
     module Symbol
+      # snake_case für Symbol, verwandel Symbol in String
       def snake_case
         to_s.snake_case
       end
@@ -264,7 +310,7 @@ module SchildErweitert
 
     # 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])
+      k = Sequel::Database::SCHEMA_TYPE_CLASSES[klass.db_schema[column][:type]]
       if k.class == Array
         # Sequel stellt :datetime als [Time, DateTime] dar, deswegen die Abfrage nach Array
         # Schild verwendet Time Objekte, wir machen das auch
@@ -283,11 +329,12 @@ module SchildErweitert
   # Halten wir Protokoll zu den erstellten Methoden
   # Ist brauchbar, wenn man z.B. noch extremer als der SchildTypeSaver arbeiten möchte
   module MethodLogger
+    # Methoden-Klasse die alles Daten sammelt
     class Methods
       @@accessor_methods = {}
 
       # Eine Methode dem MethodLogger hinzufügen
-      # @param klasse, methode
+      # @param [Class, method]
       def self.add(klass, meth)
         @@accessor_methods[klass] ||= []
         @@accessor_methods[klass] << meth
@@ -505,7 +552,6 @@ module SchildErweitert
     end
   end
 
-
   # Assoziation für BK-Abschlussdaten
   class BKAbschluss
     # Ist der Schüler zugelassen?

lib/schild/version.rb

@@ -1,3 +1,4 @@
 module Schild
+  # Die aktuelle Version
   VERSION = "0.7.12"
 end