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