Proposal: doc.go for each package

[Nate Finch]

We definitely need package-level documentation in any new package.  And
ideally, people who know existing packages without documentation would
occasionally spend some time documenting them as well.  At least with
documentation, you have a chance of understanding what a package is all
about... this is useful both for understanding the code and understanding
if new code should be put in that package.

I would hope people always write package docs when writing new packages,
but it's good to explicitly state that it is required.

On Wed, Aug 26, 2015 at 9:32 AM William Reade <william.reade at canonical.com>
wrote:

> On Wed, Aug 26, 2015 at 3:11 PM, Frank Mueller <
> frank.mueller at canonical.com> wrote:
>>
>> So, what do you think?
>>
>
> I think it's a good idea :-). I wouldn't want to mandate immediate
> introduction everywhere, but I think it's reasonable to require it for new
> code, and for non-trivial changes to older code. Not sure that's quite so
> cleanly automatable -- more of a review checklist thing, perhaps? (e.g. I'd
> consider package moves to be "trivial", but reviewboard (for example)
> doesn't handle them well at all.)
>
> Cheers
> William
>
>
>>
>> mue
>>
>> --
>> Frank Mueller <frank.mueller at canonical.com>
>> Juju Core Sapphire Team <http://jujucharms.com>
>>
>> --
>> Juju-dev mailing list
>> Juju-dev at lists.ubuntu.com
>> Modify settings or unsubscribe at:
>> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>>
>> --
> Juju-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20150826/eb9cf73d/attachment.html>