View previous topic :: View next topic |
Author |
Message |
ChristianK
Joined: 26 Sep 2006 Posts: 159 Location: Berlin, Germany
|
Posted: Wed Apr 18, 2007 1:07 am Post subject: Documentation comments for license, author, ... |
|
|
I just saw you added a cleanup of these to the roadmap, so here are my opinions:
Obnoxiously long license texts at the start of each file are annoying. One line should be okay, preferably stating the license name and referring to some LICENSE file coming with arc.
The author information I find mostly redundant - of course most of the code is witten by you and some by me. Maybe again provide a link to a file or webpage that lists past and present authors.
If the intention was to easily be able to figure out who's responsible for a file, maybe add a maintainer comment, though I think it'll just get outdated..
Of course some more header comments are required when we based our work on other people's projects, as with the physics subsystem.
This is what I propose a header comment to look like:
Code: |
/*******************************************************************************
Short description of what module does.
Authors: ArcLib team, see AUTHORS file
Maintainer: Clay Smith (obfuscated email address)
License: zlib/libpng license, see LICENSE file
The contents of this file are based on E. Catto's Box2d, which is
Copyright (c) 2006 Erin Catto http://www.gphysics.com.
Description:
A longer description, if available.
And more text for the long description.
Examples:
These are useful!
*******************************************************************************/ |
|
|
Back to top |
|
|
clayasaurus
Joined: 21 May 2004 Posts: 857
|
Posted: Wed Apr 18, 2007 8:47 am Post subject: |
|
|
That's good, although we have to keep in mind to be compatible with Ddoc.
http://www.digitalmars.com/d/ddoc.html
Maybe we can ask Walter to differentiate between authors and maintainers?
I think the license should link to the license website when viewed from Ddoc as well. |
|
Back to top |
|
|
ChristianK
Joined: 26 Sep 2006 Posts: 159 Location: Berlin, Germany
|
Posted: Wed Apr 18, 2007 10:19 am Post subject: |
|
|
Quote: | That's good, although we have to keep in mind to be compatible with Ddoc. |
Actually, the section names listed in the spec are just recommendations (ok, some have special handling, but "Author" doesn't). So adding a Maintainer section is no problem.
Quote: | I think the license should link to the license website when viewed from Ddoc as well. |
Maybe we should use a macro for the license link and optionally additional text then - I've seen this in the tango sources. Altered proposal:
Code: | /*******************************************************************************
Short description of what module does.
Authors: ArcLib team, see AUTHORS file
Maintainer: Clay Smith (obfuscated email address)
License: zlib/libpng license: $(LICENSE)
The contents of this file are based on E. Catto's Box2d, which is
Copyright (c) 2006 Erin Catto http://www.gphysics.com.
Description:
A longer description, if available.
And more text for the long description.
Examples:
These are useful!
*******************************************************************************/ |
|
|
Back to top |
|
|
clayasaurus
Joined: 21 May 2004 Posts: 857
|
Posted: Wed Apr 18, 2007 10:37 am Post subject: |
|
|
Copyright should be ddoc friendly
Copyright: (c) 2006 Erin Catto http://www.gphysics.com.
Other than that, looks good. |
|
Back to top |
|
|
ChristianK
Joined: 26 Sep 2006 Posts: 159 Location: Berlin, Germany
|
Posted: Wed Apr 18, 2007 11:20 am Post subject: |
|
|
But this adds a slew of ugly html to an otherwise terse header comment! Do we really need to have this link clickable? And why doesn't ddoc do it automatically in the first place?
Seriously though: if you think it's absolutely neccessary, I'm ok with it. |
|
Back to top |
|
|
clayasaurus
Joined: 21 May 2004 Posts: 857
|
Posted: Wed Apr 18, 2007 11:40 am Post subject: |
|
|
I think you misunderstood me.
Copyright --> : <-- Erin Cato etc.
vs.
Copyright (c) Erin Cato etc.
is all I'm talking about.
I do think the license should be clickable though, and I'm assuming this will be handled by the license macro. |
|
Back to top |
|
|
ChristianK
Joined: 26 Sep 2006 Posts: 159 Location: Berlin, Germany
|
Posted: Wed Apr 18, 2007 12:00 pm Post subject: |
|
|
Ah, yes I did indeed misunderstand you.
Yet, I don't think we should go for the colon there: If we added it, it'd give the impression that Cato still holds the sole copyright; even of the modified file.
Essentially, my opinion is that my changes to the original code are extensive enough to allow me to stamp the files with my own copyright/license - as long as it doesn't conflict with Cato's. The original license states though, that his copyright line must appear unmodified in all derivative works - so that's what we do.
I'm making common sense judgements on legal issues here, so any and all of this could be wrong. In that case though, I'm sure Cato will let us know eventually. |
|
Back to top |
|
|
clayasaurus
Joined: 21 May 2004 Posts: 857
|
Posted: Wed Apr 18, 2007 1:21 pm Post subject: |
|
|
The we'll use
Code: |
/*******************************************************************************
Short description of what module does.
Authors: ArcLib team, see AUTHORS file
Maintainer: Clay Smith (obfuscated email address)
License: zlib/libpng license: $(LICENSE)
Copyright: ArcLib team
The contents of this file are based on E. Catto's Box2d, which is
Copyright (c) 2006 Erin Catto http://www.gphysics.com.
Description:
A longer description, if available.
And more text for the long description.
Examples:
These are useful!
*******************************************************************************/
|
This look good? |
|
Back to top |
|
|
ChristianK
Joined: 26 Sep 2006 Posts: 159 Location: Berlin, Germany
|
Posted: Wed Apr 18, 2007 1:22 pm Post subject: |
|
|
Perfect! I'll add it as a comment to the ticket. |
|
Back to top |
|
|
|