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

[Peter Krempa]

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?

> work and effort which I can see you'd refuse to put into this, but I fear that
> once you drop this, we won't update the docs with another examples for
> years/ever and I'm not in favour of such practice.

No. I'll drop the series if it does not get accepted and continue
ignoring this as I've did for many years. I wanted to kill this for
some time (when I was adding syntax-check rule and the patches were
conflicting), but did not even want to bother to do that for at that
time so I've just opted to skip them.

Recent Eric's usage of the patches as an example in his mail discussing
renaming of the files triggered me to get rid of this finally.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20180823/8fc4bc91/attachment-0001.sig>