Some doco and a dist build script

.gitignore

@@ -0,0 +1,2 @@
+# Distribution artifacts
+dist/

Makefile

@@ -0,0 +1,16 @@
+# This Makefile is just for building the release distribution.
+# It's not needed for just building or running the program
+
+.PHONY: dist
+
+PROGRAM=SLF4M
+VERSION=$(shell cat VERSION)
+DIST=dist/${PROGRAM}-${VERSION}
+FILES=README.md LICENSE Mcode doc
+
+dist:
+	rm -rf dist/*
+	mkdir -p ${DIST}
+	cp -R $(FILES) $(DIST)
+	cd dist; tar czf ${PROGRAM}-${VERSION}.tgz --exclude='*.DS_Store' ${PROGRAM}-${VERSION}
+	cd dist; zip -rq ${PROGRAM}-${VERSION}.zip ${PROGRAM}-${VERSION} -x '*.DS_Store'

Mcode/+logm/Logger.m

@@ -20,6 +20,11 @@
     % logm.info
     % logm.debug
     % logm.trace
+    %
+    % Examples:
+    %
+    % log = logm.Logger.getLogger('foo.bar.FooBar');
+    % log.info('Hello, world! Running on Matlab %s', version);
 
     properties (SetAccess = private)
         % The underlying SLF4J Logger object
@@ -40,7 +45,6 @@
         jLogger = org.slf4j.LoggerFactory.getLogger(identifier);
         out = logm.Logger(jLogger);
         end
-
     end
 
     methods
@@ -52,6 +56,27 @@
         this.jLogger = jLogger;
         end
 
+        function disp(this)
+            disp(dispstr(this));
+        end
+
+        function out = dispstr(this)
+            if isscalar(this)
+                strs = dispstrs(this);
+                out = strs{1};
+            else
+                out = sprintf('%s %s', size2str(size(this)), class(this));
+            end
+        end
+
+        function out = dispstrs(this)
+            out = cell(size(this));
+            for i = 1:numel(this)
+                out{i} = sprintf('Logger: %s (%s)', this(i).name, ...
+                    strjoin(this(i).enabledLevels, ', '));
+            end
+        end
+
         function error(this, msg, varargin)
         % Log a message at the ERROR level.
         if ~this.jLogger.isErrorEnabled()

doc/User Guide.md

@@ -46,15 +46,26 @@ Normally when writing a library, I avoid defining any global functions, to avoid
 
 This provides an extension point for defining custom string conversions for your own user-defined classes. You can override `dispstr` and `dispstrs` in your classes, and SLF4M will recognize it. I find this is useful for other string formatting, too.
 
-For uniformity, if you define `dispstr`, I recommend that you override `disp` to make use of it.
+For uniformity, if you define `dispstr`, I recommend that you override `disp` to make use of it. And you'll typically want to make `dispstr` and `dispstrs` consistent.
 
 ```
     function disp(this)
         disp(dispstr(this));
     end
+
+    % Standard implementation of dispstr
+    function out = dispstr(this)
+        if isscalar(this)
+            strs = dispstrs(this);
+            out = strs{1};
+        else
+            out = sprintf('%s %s', size2str(size(this)), class(this));
+        end
+    end
+
 ```
 
-As a convenience, there is a `logm.Displayable` mix-in class which provides standard implementations of `disp` and `dispstr` in terms of `dispstrs`. If you inherit from `logm.Displayable`, you only need to define `dispstrs`.
+As a convenience, there is a `logm.Displayable` mix-in class which takes care of this boilerplate for you. It provides standard implementations of `disp` and `dispstr` in terms of `dispstrs`. If you inherit from `logm.Displayable`, you only need to define `dispstrs`.
 
 ### The `dispstr` interface