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