FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

Documentation comments for license, author, ...

 
Post new topic   Reply to topic     Forum Index -> ArcLib
View previous topic :: View next topic  
Author Message
ChristianK



Joined: 26 Sep 2006
Posts: 159
Location: Berlin, Germany

PostPosted: Wed Apr 18, 2007 1:07 am    Post subject: Documentation comments for license, author, ... Reply with quote

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
View user's profile Send private message
clayasaurus



Joined: 21 May 2004
Posts: 857

PostPosted: Wed Apr 18, 2007 8:47 am    Post subject: Reply with quote

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
View user's profile Send private message AIM Address
ChristianK



Joined: 26 Sep 2006
Posts: 159
Location: Berlin, Germany

PostPosted: Wed Apr 18, 2007 10:19 am    Post subject: Reply with quote

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
View user's profile Send private message
clayasaurus



Joined: 21 May 2004
Posts: 857

PostPosted: Wed Apr 18, 2007 10:37 am    Post subject: Reply with quote

Copyright should be ddoc friendly Smile

Copyright: (c) 2006 Erin Catto http://www.gphysics.com.

Other than that, looks good.
Back to top
View user's profile Send private message AIM Address
ChristianK



Joined: 26 Sep 2006
Posts: 159
Location: Berlin, Germany

PostPosted: Wed Apr 18, 2007 11:20 am    Post subject: Reply with quote

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
View user's profile Send private message
clayasaurus



Joined: 21 May 2004
Posts: 857

PostPosted: Wed Apr 18, 2007 11:40 am    Post subject: Reply with quote

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
View user's profile Send private message AIM Address
ChristianK



Joined: 26 Sep 2006
Posts: 159
Location: Berlin, Germany

PostPosted: Wed Apr 18, 2007 12:00 pm    Post subject: Reply with quote

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
View user's profile Send private message
clayasaurus



Joined: 21 May 2004
Posts: 857

PostPosted: Wed Apr 18, 2007 1:21 pm    Post subject: Reply with quote

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
View user's profile Send private message AIM Address
ChristianK



Joined: 26 Sep 2006
Posts: 159
Location: Berlin, Germany

PostPosted: Wed Apr 18, 2007 1:22 pm    Post subject: Reply with quote

Perfect! I'll add it as a comment to the ticket.
Back to top
View user's profile Send private message
Display posts from previous:   
Post new topic   Reply to topic     Forum Index -> ArcLib All times are GMT - 6 Hours
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2001, 2005 phpBB Group