Up to Main Index                         Up to Journal for September, 2017

                  JOURNAL FOR SATURDAY 30TH SEPTEMBER, 2017
______________________________________________________________________________

SUBJECT: Flu, documentation, exports and indecision.
   DATE: Sat 30 Sep 23:57:19 BST 2017

Ugh! Time for my yearly bought of flu and feeling rough as hell :( As a result
this entry may degenerate into a rambling, babbling mess…

While cleaning up command handling I’ve hit a snag concerning naming,
exporting and godoc. For example, in the cmd package there is a map used to
register handlers for commands. This map should not be used outside of the cmd
package and so should not be exported. However it is expected that other
people will want to add their own commands, so it should be documented. The
map has methods which should not be used outside of the cmd package and so
should not be exported, but they are expected to be used by people adding new
commands, so gain they need documenting.

Should things be exported just so they can documented — and open to misuse, or
should developers be expected to make use of unexported package features?

When using godoc to browse the documentation you can add ?m=all to the end of
a URL to see all unexported information. If you are using ‘go doc’ you can
pass the -u flag to see unexported information.

I’ve hit this problem before and didn’t decide on a good solution then. I
think last time I exported something just for the documentation, which didn’t
seem right then and doesn’t seem right now either.

You might think one answer would be to put things in an internal package and
export them. That works and only the package can use the exported features.
However the internal package is not listed under the subdirectories for a
package in godoc unless you are using the ?m=all flag. It also means that
practically every source file in the package can end up importing the internal
package.

It seems that godoc is well suited for documenting packages that are supposed
to be used as opposed to extended or added to. At the moment, looking at my
development machine, I have 26 files implementing commands in the cmd package
and the godoc shows only two functions:


  func Parse(t has.Thing, input string) string
  func Script(t has.Thing, input string) string


Hrm, not good, but what to do? I currently think keeping the code correct is
the most important thing. Exporting things only when necessary means the
documentation, which I put a lot of effort into, is not automatically shown.
People will just have to read the source or remember to use ?m=all or -u.

Going back to using internal packages, I could move cmd/state.go into
cmd/internal/state.go which would allow me to clean up state and only export
things that commands should be expected to use. As every commands needs an
instance of state, every command will have to import cmd/internal — but it
will make it more explicit as to which features commands should be using. A
prime example of this is state.locks:


  type state struct {
    actor       has.Thing     // The Thing executing the command
    where       has.Inventory // Where the actor currently is
    participant has.Thing     // The other Thing participating in the command
    input       []string      // The original input of the actor minus cmd
    cmd         string        // The current command being processed
    words       []string      // Input as uppercased words, less stopwords
    ok          bool          // Flag to indicate if command was successful
    scripting   bool          // Is state in scripting mode?

    // DO NOT MANIPULATE LOCKS DIRECTLY - use AddLock and see it's comments
    locks []has.Inventory // List of locks we want to be holding

    // msg contains the message buffers for sending data to different recipients
    msg message.Msg
  }


For that matter AddLock should not be exported outside of the cmd package
either. I guess if I move the handler code and state code into internal at
least it’ll only need a single import, but it’ll be a hell of a lot of work
for uncertain gain.

Now that WolfMUD is stable again it seems like a good time to review all of the
code. At the same time it would make sense to write all of the missing tests
while pouring over the sources. Oh what joy!

--
Diddymus


  Up to Main Index                         Up to Journal for September, 2017