Suggestion for new tag: @LICENSE

[klatham]

The JEDI project has a requirement for a standard header describing the license conditions at the top of each unit. JEDI aside, this is a standard requirement for many developments.

I think it is reasonable that this be header is included in the documentation produced by DCTD. Currently the only place to code it is in the unit description, but this distracts from the description of the unit itself.

I would like to suggest a new tag: @LICENSE which would introduce the header and improve the readability of the documentation.

Since the standard header is supposed to go at the very top of the unit, I think we need an explicit @DESCRIPTION tag to continue the description definition after the standard header.

The @LICENSE info would be placed under a newly defined LICENSE header in the doco output.

example:

{***********
Delphi Pascal Translation of Rexx API Header File

@LICENSE
{ Borland Delphi Runtime Library
{ Rexx Interface unit
...
@DESCRIPTION
This unit .....

@AUTHOR ...
@VERSION ...
*}
unit rexx;
...

[klatham]

The JEDI header does not contain the license, it describes the license used and refers the reader to the license document. It also contains other informaion like source copyright acknowledgements. Here is the JEDI suggested template for an API conversion:

{*********}
{ }
{ Borland Delphi Runtime Library }
{ <API> interface unit }
{ }
{ Portions created by Microsoft are }
{ Copyright (C) 1995-1999 Microsoft Corporation. }
{ All Rights Reserved. }
{ }
{ The original file is: urlmon.h, released 11 Nov 1997. }
{ The original Pascal code is: UrlMon.pas, released 15 Jun 1999. }
{ The initial developer of the Pascal code is Rudolph Velthuis }
{ (rvelthuis@gmx.de). }
{ }
{ Portions created by Rudolph Velthuis are }
{ Copyright (C) 1999 Rudolph Velthuis. }
{ }
{ Contributor(s): Marcel van Brakel }
{ Christopher D. Coppola }
{ }
{ Obtained through: }
{ }
{ Joint Endeavour of Delphi Innovators (Project JEDI) }
{ }
{ You may retrieve the latest version of this file at the Project }
{ JEDI home page, located at http://delphi-jedi.org }
{ }
{ The contents of this file are used with permission, subject to }
{ the Mozilla Public License Version 1.1 (the "License"); you may }
{ not use this file except in compliance with the License. You may }
{ obtain a copy of the License at }
{ http://www.mozilla.org/MPL/MPL-1.1.html }
{ }
{ Software distributed under the License is distributed on an }
{ "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or }
{ implied. See the License for the specific language governing }
{ rights and limitations under the License. }
{ }
{*********}

[TridenT]

Added a new tracker as a feature request here :
http://sourceforge.net/tracker/index.php?func=detail&aid=1839396&group_id=96281&atid=614258

We will need to discuss about tag and syntax, because we need to keep maximum compatibility with JavaDoc.

[klatham]

OK, I take your point. There is no similar tag in Javadoc, nor anything that could be 'stretched' to the purpose.

Personally, I am in favour of creating a new tag dialect that conforms to "the Pascal way" instead of "the Java way", if necessary. But its your program and you are the one that has to maintain the integrity of the concept. That's fine with me.

If you do choose to add these tags, my thought is that they would have essentially no syntax. They would merely introduce a block of text that starts on the next line and ends at the end of DCTD comment block or the next tag, whichever comes first.

Who knows, maybe the idea could end up in back in JavaDoc?

[TridenT]

TAG definitions from javaDoc website :
* Tag - Intended as a way of adding structure and content to the documentation. Allows multi-line text to be provided. (Use the -tag or -taglet Javadoc option to create custom tags.) Tags should never affect program semantics.

So, @licence is really a custom tag for us.

i would only keep the @description optional, so maybe @licence can come after the (implicit) description.
Maybe some need to refer to a file, instead of a text.

@licence "gpl.txt"

@licence <gpl.txt>

or

@licence GNU GENERAL PUBLIC LICENSE
Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

            Preamble

The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.

...

[TridenT]

to summarize :

{***********
Delphi Pascal Translation of Rexx API Header File

This unit .....

@LICENSE
{ Borland Delphi Runtime Library
{ Rexx Interface unit
...

@AUTHOR ...
@VERSION ...
*}
unit rexx;
...