cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Gill <stevengil...@gmail.com>
Subject Re: [proposal] Remove tool generated docs from camera plugin?
Date Tue, 17 Oct 2017 22:51:46 GMT
I'm fine with going back to a simple readme

On Sun, Oct 15, 2017 at 12:52 AM, julio cesar sanchez <
jcesarmobile@gmail.com> wrote:

> The README.md already have a section
> <https://github.com/apache/cordova-plugin-camera#this-
> documentation-is-generated-by-a-tool>
> about how the README.md is generated. But maybe it should be more clear and
> say that the README.md shouldn't be updated manually.
>
> BTW, I sent a PR <https://github.com/apache/cordova-plugin-camera/pull/291
> >
> to make the template be in sync with the README.md changes. If anybody can
> take a look it would be good. Not sure if I can merge while the tests are
> failing, but I only changed the template, so I'm pretty sure I didn't break
> anything and tests are failing in all other plugins, but that's another
> topic.
>
> About if it's a good idea, I've found the original cordova-discuss issue
> <https://github.com/apache/cordova-discuss/issues/15> and proposal
> <https://github.com/apache/cordova-discuss/pull/16> and reading them I
> think it's a good idea as I understand that the API part of the docs are
> automatically generated from the js files, which avoids them to be out of
> sync if a js change is made.
>
>
> 2017-10-15 1:07 GMT+02:00 Jan Piotrowski <piotrowski@gmail.com>:
>
> > The "not aware" problem can probably be resolved (80/20) by adding
> > comments to the template that are also in the generated output.
> >
> > But it the TEMPLATE.md actually a good idea? Is it worth the extra
> effort?
> >
> > -J
> >
> > 2017-10-15 0:01 GMT+02:00 julio cesar sanchez <jcesarmobile@gmail.com>:
> > > cordova-plugin-camera docs work on a different way than other plugins.
> > The
> > > README.md is generated from jsdoc2md/TEMPLATE.md when the commit is
> done.
> > > I think it was a proof of concept to be done in all the plugins, but it
> > the
> > > end it was only done in camera plugin.
> > > The problem is most people is not aware of this, so they just update
> the
> > > README.md manually as on any other plugins, and most of the committers
> > > aren't aware neither or forgot about it and just merge those changes.
> > >
> > > So, I was about to send a new PR and the jsdoc2md/TEMPLATE.md is out of
> > > sync with the README.md.
> > >
> > > So, we have two options, we can move back to a regular README.md like
> the
> > > other plugins, or do this in all the plugins and not accept README.md
> > file
> > > changes without the corresponding jsdoc2md/TEMPLATE.md.
> > >
> > > What do you think?
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
> > For additional commands, e-mail: dev-help@cordova.apache.org
> >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message