Authors, maintainers and licenses in apidox

[Kevin Ottens]

Hello,

On Wednesday 22 January 2014 12:27:29 Alex Merry wrote:
> On 22/01/14 06:33, Kevin Ottens wrote:
> > On Tuesday 21 January 2014 17:18:36 Alex Merry wrote:
> >> Traditionally, the front pages of our apidox has included a list of
> >> authors, the maintainer(s) and the license.  This is obviously
> >> duplicating/summarising information stored elsewhere, and is easy to let
> >> get out of date.
> > 
> > Yes... definitely easy to get wrong. We should have only one place for
> > that.> 
> >> Do we still want this information?  It would probably mean adding it to
> >> the README.md files.
> > 
> > Are we ditching the LICENSE and AUTHORS files which used to contain this
> > type of information? I'm not sure we want everything in README.md.
> 
> Well, this is kind of what I mean about duplicating the information.
> Although the canonical authorship info is the copyright headers and/or
> git log.
> 
> My personal view is that authors generally shouldn't be in the apidox
> main page anyway, as it's not massively useful to users of the dox.

Agreed.

> Authors on individual classes is more useful and more likely to be accurate.

Not sure I agree there... the amount of class level author info we had in 
kdelibs which was outdated look large to me.

> Having the maintain there is a possibility, or we could just add a link
> to the frameworks list with the canonical info to the Links section.

We have indeed to choose which one will be canonical: the wiki page or some 
bit in the repository. I don't mind either way, depends what maintainers 
prefer to edit really.

> License is potentially useful.  Currently the docs do
> @licenses
> @lgpl
> which gives something approximating the markdown
> ### License(s):
> [LGPLv2](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html#SEC1)
> 
> This is somewhat more succinct than the content of LICENSE tends to be
> (where that file is even given; we currently don't bother with it if the
> code is GPL or LGPL; in that case, we have COPYING or COPYING.LIB,
> containing the full text of the license, instead).
> 
> I would be tempted to ditch the current LICENSE files (all three of
> them), and add (summary) license info to README.md, as
>
> > ## License
> > 
> > This framework is licensed under the
> > [LGPLv2](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html#SEC1)
> 
> or
> 
> > ## License
> > 
> > This framework is licensed under the @lgpl
> 
> (the latter depends on a doxygen command defined by kapidox).  We would
> (have to) keep COPYING and COPYING.LIB regardless.  We might want to add
> in a second sentence saying that the CMake code is licensed as BSD.

I like that.

> Currently there are a bunch of COPYING-CMAKE-SCRIPTS files around where
> frameworks ship Find*.cmake modules, which I'm not so keen on
> (especially as the BSD license text makes little sense unless it has a
> copyright notice above it).

Agreed.

Cheers.
-- 
Kévin Ottens, http://ervin.ipsquad.net

KDAB - proud supporter of KDE, http://www.kdab.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20140122/196c9a8b/attachment.sig>