Up to Main Index Up to Journal for March, 2015 JOURNAL FOR TUESDAY 3RD MARCH, 2015 ______________________________________________________________________________ SUBJECT: Exporting for documentation? DATE: Tue 3 Mar 21:31:38 GMT 2015 I cannot believe it's March already and officially spring. I'll be glad when the weather starts warming up a bit. Clocks go forward at the end of the month as well[1]. Work has progressed on WolfMUD-mini nicely. I've even started documenting all of the code, which is where I have hit a bit of a snag. By default godoc does not show exported methods for unexported types. For example: type test struct { message string } func (t *test) Message() string { return t.message } In this simple example Message will not be displayed by godoc because test is not exported. People could just look at the source code or alternatively they could pass 'm=all' on the godoc URL. I feel neither option is ideal :( There are two suggested ways of dealing with this situation that I have come across on the gonuts group[2]. 1. Export the type 2. Document via an interface I would rather not export the type. It currently does not need to be exported and once given out it's practically impossible to rein back in again once the code is published without breaking someone else's code. For the second option I have issues documenting via an interface. On a personal level I think it looks horrible - documentation for an interface's methods are not as nicely formatted and usable as documenting type methods and functions. On a more practical note there are exported methods not covered by the interface and which should not go into the interface. Of these two options I like neither, but if I had to pick one I would export the type. For the second option I'd have to create another interface that probably wouldn't be used except for documentation. I have tried many experiments to try and solve these issues and failed. For now I am ploughing on and other developers will have to read the code or pass "m=all" on the godoc URL until I make a final decision :( -- Diddymus [1] On the 29th March this year - clocks go forward an hour at 1am on the last Sunday in March. [2] https://groups.google.com/group/golang-nuts Up to Main Index Up to Journal for March, 2015