better SUnit class comments

js/SUnit.js

@@ -1,5 +1,6 @@
 smalltalk.addPackage('SUnit');
 smalltalk.addClass('ResultAnnouncement', smalltalk.Object, ['result'], 'SUnit');
+smalltalk.ResultAnnouncement.comment="I get signaled when a `TestCase` has been run.\x0a\x0aMy instances hold the result (instance of `TestResult`) of the test run."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "result",
@@ -37,7 +38,7 @@ smalltalk.ResultAnnouncement);
 
 
 smalltalk.addClass('TestCase', smalltalk.Object, ['testSelector', 'asyncTimeout', 'context'], 'SUnit');
-smalltalk.TestCase.comment="A TestCase is an implementation of the command pattern to run a test.\x0a\x0a`TestCase` instances are created with the class method `#selector:`,\x0apassing the symbol that names the method to be executed when the test case runs.\x0a\x0aWhen you discover a new fixture, subclass `TestCase` and create a `#test...` method for the first test.\x0aAs that method develops and more `#test...` methods are added, you will find yourself refactoring temps\x0ainto instance variables for the objects in the fixture and overriding `#setUp` to initialize these variables.\x0aAs required, override `#tearDown` to nil references, release objects and deallocate."
+smalltalk.TestCase.comment="I am an implementation of the command pattern to run a test.\x0a\x0a## API\x0a\x0aMy instances are created with the class method `#selector:`,\x0apassing the symbol that names the method to be executed when the test case runs.\x0a\x0aWhen you discover a new fixture, subclass `TestCase` and create a `#test...` method for the first test.\x0aAs that method develops and more `#test...` methods are added, you will find yourself refactoring temps\x0ainto instance variables for the objects in the fixture and overriding `#setUp` to initialize these variables.\x0aAs required, override `#tearDown` to nil references, release objects and deallocate."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "assert:",
@@ -574,7 +575,7 @@ smalltalk.TestCase.klass);
 
 
 smalltalk.addClass('TestContext', smalltalk.Object, ['testCase'], 'SUnit');
-smalltalk.TestContext.comment="TestContext governs running a particular test case.\x0a\x0aIt's main added value is `#execute:` method which runs a block\x0aas a part of test case (restores context, nilling it afterwards,\x0acleaning/calling tearDown as appropriate for sync/async scenario)."
+smalltalk.TestContext.comment="I govern running a particular test case.\x0a\x0aMy main added value is `#execute:` method which runs a block as a part of test case (restores context, nilling it afterwards, cleaning/calling `#tearDown` as appropriate for sync/async scenario)."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "execute:",
@@ -675,7 +676,7 @@ smalltalk.TestContext.klass);
 
 
 smalltalk.addClass('ReportingTestContext', smalltalk.TestContext, ['finished', 'result'], 'SUnit');
-smalltalk.ReportingTestContext.comment="ReportingTestContext adds `TestResult` reporting\x0ato `TestContext`.\x0a\x0aErrors are caught and save into a `TestResult`,\x0aWhen test case is finished (which can be later for async tests),\x0aa callback block is executed; this is used by a `TestSuiteRunner`."
+smalltalk.ReportingTestContext.comment="I add `TestResult` reporting to `TestContext`.\x0a\x0aErrors are caught and save into a `TestResult`,\x0aWhen test case is finished (which can be later for async tests), a callback block is executed; this is used by a `TestSuiteRunner`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "execute:",
@@ -790,11 +791,11 @@ smalltalk.ReportingTestContext.klass);
 
 
 smalltalk.addClass('TestFailure', smalltalk.Error, [], 'SUnit');
-smalltalk.TestFailure.comment="The test framework distinguishes between failures and errors.\x0aA failure is an event whose possibiity is explicitly anticipated and checked for in an assertion,\x0awhereas an error is an unanticipated problem like a division by 0 or an index out of bounds.\x0a\x0aTestFailure is raised when the boolean parameter of an #`assert:` or `#deny:` call is the opposite of what the assertion claims."
+smalltalk.TestFailure.comment="I am raised when the boolean parameter of an #`assert:` or `#deny:` call is the opposite of what the assertion claims.\x0a\x0aThe test framework distinguishes between failures and errors.\x0aA failure is an event whose possibiity is explicitly anticipated and checked for in an assertion,\x0awhereas an error is an unanticipated problem like a division by 0 or an index out of bounds."
 
 
 smalltalk.addClass('TestResult', smalltalk.Object, ['timestamp', 'runs', 'errors', 'failures', 'total'], 'SUnit');
-smalltalk.TestResult.comment="A TestResult implements the collecting parameter pattern for running a bunch of tests.\x0a\x0aA TestResult holds tests that have run, sorted into the result categories of passed, failures and errors.\x0a\x0aTestResult is an interesting object to subclass or substitute. `#runCase:` is the external protocol you need to reproduce"
+smalltalk.TestResult.comment="I implement the collecting parameter pattern for running a bunch of tests.\x0a\x0aMy instances hold tests that have run, sorted into the result categories of passed, failures and errors.\x0a\x0a`TestResult` is an interesting object to subclass or substitute. `#runCase:` is the external protocol you need to reproduce"
 smalltalk.addMethod(
 smalltalk.method({
 selector: "addError:",
@@ -1055,6 +1056,7 @@ smalltalk.TestResult);
 
 
 smalltalk.addClass('TestSuiteRunner', smalltalk.Object, ['suite', 'result', 'announcer', 'runNextTest'], 'SUnit');
+smalltalk.TestSuiteRunner.comment="I am responsible for running a collection (`suite`) of tests.\x0a\x0a## API\x0a\x0aInstances should be created using the class-side `#on:` method, taking a collection of tests to run as parameter.\x0aTo run the test suite, use `#run`."
 smalltalk.addMethod(
 smalltalk.method({
 selector: "announcer",

st/SUnit.st

@@ -2,6 +2,10 @@ Smalltalk current createPackage: 'SUnit'!
 Object subclass: #ResultAnnouncement
 	instanceVariableNames: 'result'
 	package: 'SUnit'!
+!ResultAnnouncement commentStamp!
+I get signaled when a `TestCase` has been run.
+
+My instances hold the result (instance of `TestResult`) of the test run.!
 
 !ResultAnnouncement methodsFor: 'accessing'!
 
@@ -17,9 +21,11 @@ Object subclass: #TestCase
 	instanceVariableNames: 'testSelector asyncTimeout context'
 	package: 'SUnit'!
 !TestCase commentStamp!
-A TestCase is an implementation of the command pattern to run a test.
+I am an implementation of the command pattern to run a test.
+
+## API
 
-`TestCase` instances are created with the class method `#selector:`,
+My instances are created with the class method `#selector:`,
 passing the symbol that names the method to be executed when the test case runs.
 
 When you discover a new fixture, subclass `TestCase` and create a `#test...` method for the first test.
@@ -188,11 +194,9 @@ Object subclass: #TestContext
 	instanceVariableNames: 'testCase'
 	package: 'SUnit'!
 !TestContext commentStamp!
-TestContext governs running a particular test case.
+I govern running a particular test case.
 
-It's main added value is `#execute:` method which runs a block
-as a part of test case (restores context, nilling it afterwards,
-cleaning/calling tearDown as appropriate for sync/async scenario).!
+My main added value is `#execute:` method which runs a block as a part of test case (restores context, nilling it afterwards, cleaning/calling `#tearDown` as appropriate for sync/async scenario).!
 
 !TestContext methodsFor: 'accessing'!
 
@@ -238,12 +242,10 @@ TestContext subclass: #ReportingTestContext
 	instanceVariableNames: 'finished result'
 	package: 'SUnit'!
 !ReportingTestContext commentStamp!
-ReportingTestContext adds `TestResult` reporting
-to `TestContext`.
+I add `TestResult` reporting to `TestContext`.
 
 Errors are caught and save into a `TestResult`,
-When test case is finished (which can be later for async tests),
-a callback block is executed; this is used by a `TestSuiteRunner`.!
+When test case is finished (which can be later for async tests), a callback block is executed; this is used by a `TestSuiteRunner`.!
 
 !ReportingTestContext methodsFor: 'accessing'!
 
@@ -290,21 +292,21 @@ Error subclass: #TestFailure
 	instanceVariableNames: ''
 	package: 'SUnit'!
 !TestFailure commentStamp!
+I am raised when the boolean parameter of an #`assert:` or `#deny:` call is the opposite of what the assertion claims.
+
 The test framework distinguishes between failures and errors.
 A failure is an event whose possibiity is explicitly anticipated and checked for in an assertion,
-whereas an error is an unanticipated problem like a division by 0 or an index out of bounds.
-
-TestFailure is raised when the boolean parameter of an #`assert:` or `#deny:` call is the opposite of what the assertion claims.!
+whereas an error is an unanticipated problem like a division by 0 or an index out of bounds.!
 
 Object subclass: #TestResult
 	instanceVariableNames: 'timestamp runs errors failures total'
 	package: 'SUnit'!
 !TestResult commentStamp!
-A TestResult implements the collecting parameter pattern for running a bunch of tests.
+I implement the collecting parameter pattern for running a bunch of tests.
 
-A TestResult holds tests that have run, sorted into the result categories of passed, failures and errors.
+My instances hold tests that have run, sorted into the result categories of passed, failures and errors.
 
-TestResult is an interesting object to subclass or substitute. `#runCase:` is the external protocol you need to reproduce!
+`TestResult` is an interesting object to subclass or substitute. `#runCase:` is the external protocol you need to reproduce!
 
 !TestResult methodsFor: 'accessing'!
 
@@ -383,6 +385,13 @@ runCase: aTestCase
 Object subclass: #TestSuiteRunner
 	instanceVariableNames: 'suite result announcer runNextTest'
 	package: 'SUnit'!
+!TestSuiteRunner commentStamp!
+I am responsible for running a collection (`suite`) of tests.
+
+## API
+
+Instances should be created using the class-side `#on:` method, taking a collection of tests to run as parameter.
+To run the test suite, use `#run`.!
 
 !TestSuiteRunner methodsFor: 'accessing'!