The Trunk: Help-Squeak-Project-pre.64.mcz

Patrick Rein uploaded a new version of Help-Squeak-Project to project The Trunk:
http://source.squeak.org/trunk/Help-Squeak-Project-pre.64.mcz

==================== Summary ====================

Name: Help-Squeak-Project-pre.64
Author: pre
Time: 25 January 2019, 5:49:28.024527 pm
UUID: 38ec0b40-fb27-a143-8b8d-f4b6d99665f0
Ancestors: Help-Squeak-Project-pre.63

Adds a help topic on the message categories commonly used in the system. This is not done by any means but should provide an initial overview. This includes a test cases which ensures that the examples used in the documentation are actually in the categories for which they are used as examples.

=============== Diff against Help-Squeak-Project-pre.63 ===============

Item was added:
+ SqueakToolsHelp subclass: #SqueakMessageCategoriesHelp
+ instanceVariableNames: ''
+ classVariableNames: ''
+ poolDictionaries: ''
+ category: 'Help-Squeak-Project'!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp class>>addAllCategoriesTopicTo: (in category 'converting') -----
+ addAllCategoriesTopicTo: newTopic
+
+ | mapping allCategoriesTopic |
+ allCategoriesTopic := HelpTopic
+ title: 'All message categories'
+ icon: (HelpIcons iconNamed: #bookIcon)
+ contents: 'This topic contains a list of all message categories used in the system'.
+
+ mapping := IdentityDictionary new.
+ SystemNavigation allBehaviorsDo: [:behavior |
+ ((behavior organization categories
+ reject: [:category | category first = $*])
+ collect: [:category | (category findTokens: '-') first withBlanksTrimmed])
+ do: [:category |
+ (mapping at: category asLowercase asSymbol ifAbsentPut: [Set new]) add: behavior]].
+
+ mapping keys sorted do: [:categoryName |
+ allCategoriesTopic addSubtopic: (HelpTopic
+ title: categoryName
+ icon: (HelpIcons iconNamed: #pageIcon)
+ contents: (((mapping at: categoryName) collect: [:c | c printString]) sorted joinSeparatedBy: ',' , String crlf))].
+
+ ^ newTopic addSubtopic: allCategoriesTopic!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp class>>addCategoryTopicsTo: (in category 'private') -----
+ addCategoryTopicsTo: aTopic
+
+ self selectors sorted do: [:selector | | helpContents examples |
+ examples := (self new perform: selector).
+ examples := examples isCollection ifTrue: [examples] ifFalse: [#()].
+
+ helpContents := (self commentsAt: selector) first asText,
+ String crlf asText , String crlf asText ,
+ ('Examples:' asText allBold; yourself) ,
+ String crlf asText ,
+ ((examples collect: [:m | m reference]) joinSeparatedBy: ', ') asText.
+
+ aTopic addSubtopic: ((HelpTopic
+ title: (self organization categoryOfElement: selector)
+ icon: (HelpIcons iconNamed: #pageIcon)
+ contents: helpContents)
+ priority: 999;
+ yourself)]!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp class>>asHelpTopic (in category 'converting') -----
+ asHelpTopic
+
+ | newTopic |
+ newTopic := HelpTopic
+ title: 'Message categories'
+ icon: (HelpIcons iconNamed: #bookIcon)
+ contents: self mainTopicExplanation.
+
+ self
+ addCategoryTopicsTo: newTopic;
+ addAllCategoriesTopicTo: newTopic.
+
+ ^ newTopic
+ !

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp class>>mainTopicExplanation (in category 'converting') -----
+ mainTopicExplanation
+
+ ^ 'Message categories are useful for readers of a class to distinguish between different aspects of the class. Depening on the category users might have a different perspective on the class they look at.'!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp class>>priority (in category 'accessing') -----
+ priority
+
+ ^ 9999 "at the bottom"!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>arithmetic (in category 'arithmetic') -----
+ arithmetic
+ "This category contains methods implementing all kinds of arithmetic operations. Note that the content of the method and not the selector is relevant for whether a method belongs to that category. A method with the selector #+ that implements the composition of two things which is not the arithmetic addition does not belong here.  (For example TraitComposition>>#+)"
+
+ ^ {Fraction>>#+ . Point>>#//}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>comparing (in category 'comparing') -----
+ comparing
+ "This category contains all methods for comparing objects. The main selectors are #= and #hash which should both be implemented consistently. Subclasses such as Magnitude add specialized selectors such as #<=."
+
+ ^ { Object>>#= . String>>#charactersExactlyMatching: }!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>converting (in category 'converting') -----
+ converting
+ "This category contains methods for converting objects to other representations.
+ Note: For converting to string representations for displaying or storing see the 'printing' category."
+
+ ^ {Object>>#asString . PositionableStream>>#asBinaryOrTextStream}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>copying (in category 'copying') -----
+ copying
+ "This category contains methods for different ways to copy an object. The standard method is #copy which is mapped to specialized methods."
+
+ ^ {Object>>#postCopy . String>>#copyReplaceTokens:with: }!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>debugging (in category 'debugging') -----
+ debugging
+ "The debugging category contains all kinds of methods related to debugging."
+
+ ^ {Object>>#inspectOnce . Object>>#haltIf:}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>displaying (in category 'displaying') -----
+ displaying
+ "In the context of the ST80 package this category contains methods for displaying an object on screen. This is related to the drawing category in Morphic."
+
+ ^ {FormView>>#displayOn: . Circle>>#displayOn:at:clippingBox:rule:fillColor:}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>drawing (in category 'drawing') -----
+ drawing
+ "In the context of the Morphic package, the drawing category contains the methods for displaying a Morph on the screen. The main entry points are the 'drawOn:' methods. This category is related to the displaying category in the ST80 package."
+
+ ^ {EllipseMorph>>#drawOn: . HandMorph>>#fullDrawOn:}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>enumerating (in category 'enumerating') -----
+ enumerating
+ "This category is mostly found with classes representing some form of collection. The methods in this category allow all sorts of iteration and enumeration on the receiver."
+
+ ^ {Collection>>#select: . HelpBrowser>>#do:}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>eventHandling (in category 'event handling') -----
+ eventHandling
+ "In the context of the Morphic package, this category defines methods for processing events and methods Morph classes can override to handle particular events."
+
+ ^ {Morph>>#hasFocus . ScrollPane>>#handlesKeyboard:}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>examples (in category 'examples') -----
+ examples
+ "This category is mostly found on meta classes. The methods in this category can be called to create an example instance for the class."
+
+ ^ {SystemProgressMorph class>>#exampleLabelOnly . Form class>>#exampleShrink}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>failures (in category 'failures') -----
+ failures
+ "This category is most often used with TestCase classes. It contains any methods denoting failures for this TestCase"
+
+ ^ {RectangleTest>>#expectedFailures}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>initializeRelease (in category 'initialize-release') -----
+ initializeRelease
+ "This category contains methods related to initializing and, seldomly, releasing objects. The most common method in here is the #initialize method and any related methods. Further, this category also sometimes includes methods used by clients of the object to set an initial state after the object was initialized by #initialize."
+
+ ^ {WeakRegistry>>#initialize . RxMatcher>>#initialize:ignoreCase:}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>instanceCreation (in category 'instance creation') -----
+ instanceCreation
+ "This category contains methods for creating instances. Most often these are implemented for the class object."
+
+ ^ {TestCase class>>#selector: . Symbol class>>#empty}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>layout (in category 'layout') -----
+ layout
+ "In the context of the Morphic package, the layout category contain methods for setting layout policies or layout properties. In subcategories it futher contains methods for controling context menus for setting the layout parameters."
+
+ ^ {Morph>>#fullBounds . StringMorph>>#fitContents}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>menu (in category 'menu') -----
+ menu
+ "This category includes all methods related to menus, often context menus in particular. It contains methods defining the menu as well as often callbacks for the labels of menu items or the actions to be executed. Sometimes the menus are split up in different categories if there are multiple menus or submenus."
+
+ ^ {DictionaryInspector>>#mainFieldListMenu: . SystemWindow>>#makeClosable}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>printing (in category 'printing') -----
+ printing
+ "This category contains methods for creating a textual representation of an object, may it be for displaying (#printString) or storing (#storeOn:)."
+
+ ^ {Character>>#printOn: . Object>>#storeString}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>private (in category 'private') -----
+ private
+ "This category contains methods which are only (and should only be) used by the containing class and its relatives up and down the class hierarchy. Often these methods expect a particular object state and are only useful in a particular control flow. One common reason for that is that the method is only a substep of a more elaborate process."
+
+ ^ {Monitor>>#privateCleanup . Collection>>#emptyCheck}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>removing (in category 'removing') -----
+ removing
+ "The 'removing' category is mostly used with objects representing collections of some kind and include methods for "
+
+ ^ {MethodDictionary>>#removeAll . ProcessorScheduler>>#remove:ifAbsent:}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>running (in category 'running') -----
+ running
+ "In the context of a TestCase class, the 'running' category most often contains the #setUp and #tearDown methods."
+
+ ^ {ClipboardTest>>#setUp . LocaleTest>>#tearDown}!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>testing (in category 'testing') -----
+ testing
+ "The testing category contains predicate methods which typically answer a Boolean value."
+
+ ^ {SMPackage>>#isAvailable . FontImporterFontDescription>>#hasChildren}
+ !

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp>>tests (in category 'tests') -----
+ tests
+ "The tests category contains test methods in a TestCase class."
+
+ ^ {MCAncestryTest>>#testLinearPath . DurationTest>>#testNegated}
+
+ !

Item was added:
+ TestCase subclass: #SqueakMessageCategoriesHelpTest
+ instanceVariableNames: ''
+ classVariableNames: ''
+ poolDictionaries: ''
+ category: 'Help-Squeak-Project'!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelpTest>>testCategoriesAreConsistent (in category 'tests') -----
+ testCategoriesAreConsistent
+
+ | helpInstance |
+ helpInstance := SqueakMessageCategoriesHelp new.
+ SqueakMessageCategoriesHelp selectors do: [:selector | |correctCategory|
+ correctCategory := SqueakMessageCategoriesHelp organization categoryOfElement: selector.
+ (helpInstance perform: selector) do: [:method |
+ self
+ assert: ((method methodClass organization categoryOfElement: method selector) beginsWith: correctCategory)
+ description: 'Expected category ' , correctCategory]]!

Item was added:
+ ----- Method: SqueakToolsDebuggerHelp class>>priority (in category 'pages') -----
+ priority
+
+ ^ 30!

Item was added:
+ ----- Method: SqueakToolsTranscriptHelp class>>priority (in category 'pages') -----
+ priority
+
+ ^ 20!

Item was added:
+ ----- Method: SqueakToolsWorkspaceHelp class>>priority (in category 'pages') -----
+ priority
+
+ ^ 10!