[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [libvirt] [PATCH 1/5] docs: api_extension: Remove links to the stale example patches



On Thu, Aug 23, 2018 at 03:55:16PM +0200, Peter Krempa wrote:
> On Thu, Aug 23, 2018 at 15:46:30 +0200, Erik Skultety wrote:
> > On Thu, Aug 23, 2018 at 10:50:30AM +0200, Peter Krempa wrote:
> > > The pathches used as an example for the api_extension manual don't hold
> >
> > s/pathches/patches
> >
> > > up to the current standards any more. Carefully remove links and
> > > mentions of the patches from the docs.
> >
> > While I understand the impetus for the change, I am personally not convinced
> > that we want to get rid of practical examples as a means of reference to the
> > text, it's like a product documentation without examples - "hardcore mode".
>
> Any example will always become obsolete. I find trying to update it to
> be a waste of time.
>
> Users are always welcome to inspire from any existing piece of code. We
> are open-source in the end. I don't really think we need as much
> hand-holding in this area.
>
> > The fact that we took a patch series from the list archives as a reference
> > probably wasn't the best thing to do, I think we should instead come up with a
> > dummy API exercising all the sections in the docs which will conform to our
>
> Even coding style will become obsolete. Just the fact that we started
> using the autofree stuff will make many existing examples obsolete.
>
> > current standards and which we can update as we please. I know that's much more
>
> We don't even keep our coding style guidelines up to date most of the
> time. Do you think this would be any different?

That's a good point. In fact, not just that, once we split the daemon into
multiple daemons, it's likely that the guide itself might need updating, let's
see how that will turn out.

You already got a RB from Jano and since I'm undecided here, whatever.

Erik


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]