Improve the description of task 04

There were some inconsistencies, typos, wrong examples and missing clarifications.

tasks/05/README.md

@@ -36,20 +36,20 @@ Git е система за менажиране на версии на файл
 дали тя е била успешна или не.
 
 Върнатият обект отговаря на методите:
- * `message`, връщайки пояснително съобщение за извършената операция.
- * `success?` и `error?` със стойностите `true` и `false`, в зависимост от
+
+* `message`, връщайки пояснително съобщение за извършената операция.
+* `success?` и `error?` със стойностите `true` и `false`, в зависимост от
 това дали операцията е била успешна или не.
- * При успешна операция е възможно върнатият обект да отговаря на метода
+* При успешна операция е възможно върнатият обект да отговаря на метода
 `result`, връщайки друг обект - резултат от операцията, но това не е
 задължително за всяка операция.
 
 По-долу са изброени поддържаните операции, заедно с очакваните резултати.
 
 ## Транзакция (commit)
 
-Промяната на обекти в хранилището става атомарно, в рамките на транзакции.
-За да добавите обект в текущата транзакция използвате метода `add` на хранилището.
-За да изпълните транзакцията използвате метода `commit` на хранилището.
+За да добавите обект в хранилището, използвате метода `ObjectStore#add`. За да
+завършите "транзакцията", използвате метода `commit` на хранилището.
 
     repo.add("important", "This is my first version.")
     repo.add("not_so_important", "This is just a note.")
@@ -63,25 +63,25 @@ Git е система за менажиране на версии на файл
 Резултатът от метода `add` е успех:
 
     message: "Added $name$ to stage." # $name$ e името, под което ще запишем обекта.
-    result: Стойността на обекта.
+    result: Добавеният току-що обект.
 
 ### commit
 
     # commit(message)
     repo.commit("A commit message goes here...")
 
-Резултатът от метода `commit` при 0 добавени обекта е грешка:
+Резултатът от метода `commit` при 0 променени обекта е грешка:
 
     message: "Nothing to commit, working directory clean."
 
-Резултатът от метода `commit` при добавени обекти е успех:
+Резултатът от метода `commit` при променени обекти е успех:
 
-    message: "$message$\n\t$count$ files changed" # $message$ е commit съобщението. $count$ е броят на променените обекти.
+    message: "$message$\n\t$count$ objects changed" # $message$ е commit съобщението. $count$ е броят на променените обекти.
 
 ### remove
 
 Може да използвате метода `remove` на хранилището, за да премахнете обект.
-Премахнатият обект може да бъде добавен отново в следваща транзакция.
+Премахнатият обект може да бъде добавен отново в следващ commit.
 
     # remove(name)
     repo.remove("not_so_important")
@@ -93,8 +93,8 @@ Git е система за менажиране на версии на файл
 
 Резултатът от метода `remove` при съществуващ обект с това име е успех:
 
-    message: "Added name for removal." # $name$ e името, под което сме записали обекта.
-    result: Стойността на обекта.
+    message: "Added $name$ for removal." # $name$ e името, под което сме записали обекта.
+    result: Обектът, добавен за премахване.
 
 ### checkout
 
@@ -108,30 +108,36 @@ Git е система за менажиране на версии на файл
 
     message: "Commit $hash$ does not exist." # $hash$ e Sha1 hash-а на commit-а.
 
+Как се конструира `$hash$`-ът на даден commit е обяснено по-долу, в секцията за
+история на commit-ите.
+
 Резултатът от метода `checkout` при съществуващ commit с този hash е успех:
 
-    message: "HEAD is now at $hash$" # $hash$ е Sha1 hash-а на commit-а
+    message: "HEAD is now at $hash$." # $hash$ е Sha1 hash-а на commit-а
     result: Commit-ът, към който сте се върнали.
 
 ## Разклонение (branch)
 
 Branch-овете ви позволяват да променяте обектите си по независими начини.
 
 При създаване на хранилище по подразбиране се създава branch с името "master"
-и той става актуален.
+и той става активен (текущ).
+
+Всяко хранилище трябва да има инстанционен метод `branch`, който да връща обект,
+отговарящ като минимум на описания по-долу интерфейс.
 
 ### create
 
 Възможно е в даден момент да създадете няколко различни клона на обектите,
 намиращи се в хранилището, позволявайки те да се променят независимо. Това
-става с помощта на метода `branch.create` на хранилището.
+става с помощта на метода `create` на обекта, върнат от `ObjectStore#branch`.
 
     # create(branch_name)
     repo.branch.create("develop")
 
 Резултатът от метода `branch.create` при вече съществуващ branch с това име е грешка:
 
-    message: "Branch $name$ already exists" # $name$ e името, което сте избрали за новия branch.
+    message: "Branch $name$ already exists." # $name$ e името, което сте избрали за новия branch.
 
 Резултатът от метода `branch.create` при несъществуващ branch с това име е успех:
 
@@ -147,7 +153,7 @@ Branch-овете ви позволяват да променяте обекти
     # checkout(branch_name)
     repo.branch.checkout("develop")
 
-От тук нататък добавянето на нови обекти в хранилището променя историята от
+От тук нататък, добавянето на нови обекти в хранилището променя историята от
 commit-и на "develop" branch-а, останалите branch-ове не се променят.
 
 Резултатът от метода `branch.checkout` при несъществуващ branch с това име е грешка:
@@ -179,29 +185,68 @@ commit-и на "develop" branch-а, останалите branch-ове не се
 
 ### list
 
-За да проверите какви branch-ове съществуват в хранилището може да използвате метода
-`branch.list`.
+За да проверите какви branch-ове съществуват в хранилището, може да използвате
+метода `branch.list`. Този метод винаги връща успех, като в съобщението на
+резултата са изредени всички налични branch-ове, сортирани във възходящ
+лексикографски (азбучен) ред. Всяко име на branch се намира на самостоятелен
+ред в текста на съобщението. Ако branch-ът е текущия, то името му се предшества
+от текста `* ` (звезда и интервал), а ако не е текущия – от два интервала.
 
+Например, ако имаме следния код:
+
+    # list()
+    repo.branch.create("develop")
     repo.branch.list
 
+Тогава върнатият от `list` обект ще има метод `message`, който трябва да връща
+следния текст:
+
+    message: "  develop\n* master"
+
 ## История на commit-ите (log)
 
-Във всеки един момент може да видите историята от commit-и в даден branch,
-използвайки метода `log` на хранилището.
+Във всеки един момент може да видите историята от commit-и в текущо активния
+branch, използвайки метода `log` на хранилището.
 
-    git.log
+    repo.log
 
 Резултатът от метода `log` при несъществуващи commit-и в текущия branch е грешка:
 
     message: "Branch $name$ does not have any commits yet." # $name$ е името на текущия branch.
 
 Резултатът от метода `log` при съществуващи commit-и в текущия branch е успех:
 
-    message: "Commit $hash$\nDate: $date$\n\t$message$" # Повтаря се за всеки commit в текущия branch. Commit-ите се разделят с нов ред. Последният commit се намира в началото на съобщението.
+    message: "Commit $hash$\nDate: $date$\n\n\t$message$"
+    # Повтаря се за всеки commit в текущия branch. Commit-ите се разделят с празен ред (т.е.
+    # два символа за нов ред). Последният commit се намира в началото на съобщението.
+    #
     # $message$ e съобщението на commit-а.
-    # $date$ е датата, в която е направен commit-а, във формат "<ден от седмицата> <месец> <ден от месец> <час>:<минути> <година> <часова зона в часове и минути спрямо UTC>". Пример: "Fri Nov 6 14:15 2015 +0000".
+    # $date$ е датата, в която е направен commit-а, във формат
+    # "<ден от седмицата> <месец> <ден от месец> <час>:<минути> <година> <часова зона в часове и минути спрямо UTC>".
+    # Пример: "Fri Nov 6 14:15 2015 +0000".
     # $hash$ е Sha1 hash на текста "$date$$message$".
 
+Например, ако имаме следното хранилище:
+
+    repo = ObjectStore.init
+    repo.add('foo1', :bar1)
+    repo.commit('First commit')
+
+    repo.add('foo2', :bar2)
+    repo.commit('Second commit')
+
+То ако изведем на екрана резултата от `repo.log.message`, ще видим следното:
+
+    Commit aae266d7a5fc76773744bd255ab6251c5df8ae40
+    Date: Thu Nov 12 12:04:54 2015 +0200
+
+        Second commit
+
+    Commit c96e8e024543d3378a302f3b603c6ee5d99f4673
+    Date: Thu Nov 12 12:04:38 2015 +0200
+
+        First commit
+
 ## Последен commit (head)
 
 Методът `head` на хранилището ви дава достъп до последния commit в текущия branch.
@@ -213,11 +258,22 @@ commit-и на "develop" branch-а, останалите branch-ове не се
 Резултатът от метода `head` при съществуващи commit-и в текущия branch е успех:
 
     message: "$message$" # $message$ e съобщението на последния commit в текущия branch.
-    result: Последния commit в текущия branch. Той трябва да отговаря на методите date, message, hash и objects, които да връщат времето на създаване на commit-а, неговото съобщение, Sha1 hash-а му и списък от обектите, които са променени с него (без значение от реда).
+    result: Обект, представляващ последния commit в текущия branch.
+
+Обектът, връщан от метода `result` на резултата на `head`, представлява commit
+обект. Този обект трябва да отговаря на следните методи:
+
+* `date` - времето на създаване на commit-а като инстанция на вградения в Ruby
+  клас `Time`
+* `message` - съобщението на commit-а като низ
+* `hash` - Sha1 hash-а на commit-а
+* `objects` - списък от всички обекти, налични в хранилището към момента на
+  commit-а, в най-актуалната им към момента на commit-а версия. Редът, в който
+  ще ги върнете, няма значение.
 
 ## Търсене на обект (get)
 
-Търсенето на обект в хранилище се съобразява с всички commit-и в актуалния
+Търсенето на обект в хранилище се съобразява с всички commit-и в текущо активния
 branch на хранилището. С най-голяма тежест е последният commit. Ако един
 обект е добавен в commit и е премахнат в следващ, той не може да бъде достъпен
 от `get`. `get` връща най-актуалната версия на обекта.
@@ -231,6 +287,20 @@ branch на хранилището. С най-голяма тежест е по
 
 Резултатът от метода `get` при открит обект е успех:
 
-    message: "$message$" # $message$ e съобщението на последния commit, модифицирал търсения обект.
+    message: "Found object $name$." # $name$ e името на търсения обект.
     result: Търсеният обект.
 
+## Бележки
+
+Не е необходимо да мислите за клониране на обектите, които биват добавени в
+хранилището. Ако някой добави и commit-не обект тип "речник" в хранилището и
+след това мутира речника, това не ви интересува. Няма да има такива тестове.
+
+Можете да създавате колкото искате допълнителни класове, да влагате класове в
+класове и модули и т.н. Всеки клас може да има колкото искате допълнителни
+методи, ако отговаря на ограниченията и на минималния интерфейс, описан в
+условието.
+
+Разрешено е да ползвате вградени в Ruby библиотеки (част от т.нар. "стандартна
+библиотека", накратко stdlib). Ако ползвате такава, трябва да я заредите в
+началото на решението си с `require 'име_на_библиотеката'`.