Proposal: :deprecated and :added tags in metadata

[Tom Faulhaber]

Hi all,

In order to allow autodoc to consistently present information about
functions coming and going, I recommend a convention (to be followed
strictly in clojure itself) of marking namespaces, functions, vars,
etc. with tags to represent their state:

1) ^{:deprecated "1.2"} would indicate that the namespace/var was
deprecated in release 1.2.

2) ^{:added "1.2"} would indicate that the namespace/var was added in
release 1.2. (This type of annotation is throughout the python doc and
is useful when you're trying to write programs that are backwards
compatible or when you're just trying to scan changes).

I think we should:

1) Implement the deprecation tag immediately (especially for all the
contrib compatibility stuff like duck-streams) as part of the 1.2
release. We may also want to update the doc function to show the value
of this flag.

2) Add the :added tag to all functions in clojure itself after the 1.2
release (I'll volunteer to do the first, catch-up pass for this).

In addition to allowing me to generate friendly, consistent
documentation, these will also be useful for IDEs, program checkers,
etc.

Does this sound like the right approach to folks?

Tom

--
You received this message because you are subscribed to the Google Groups "Clojure Dev" group.
To post to this group, send email to cloju...@googlegroups.com.
To unsubscribe from this group, send email to clojure-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/clojure-dev?hl=en.

[Laurent PETIT]

Out of my head : would a :moved key be useful ? It would help the
migration in a structured way, with support from autodoc ?

(ns #^{ :deprecated true :moved clojure.io} clojure.contrib.duck-stream ...)

Sort of

2010/4/27 Tom Faulhaber <tomfau...@gmail.com>:

[Alex Taggart]

If it's worth anything, java uses "since" to denote when a feature was first provided.

[Tom Faulhaber]

I thought about :moved, too, but it seemed like a slippery slope to more complexity to me (cause syntax/semantics might change, the actual name of the var might change, etc.). Maybe that should just be part of the docstring. On the other hand, if we think it's the right thing, I'd be happy to support it.

Yeah, I like :since better. I was looking at python doc when I wrote that :-).

Tom

[Laurent PETIT]

2010/4/27 Tom Faulhaber <tomfau...@gmail.com>:

> I thought about :moved, too, but it seemed like a slippery slope to more
> complexity to me (cause syntax/semantics might change, the actual name of
> the var might change, etc.). Maybe that should just be part of the
> docstring. On the other hand, if we think it's the right thing, I'd be happy
> to support it.

Mmm, maybe you're right. On another hand, if it's part of the
docstring, it's even worse, since few things can be done to detect
that the var has once more been moved. With :moved , one could (but
will anyone do this ?) write a checker to verify the existence. All in
all, if we support deprecated stuff, wouldn't it be graceful to help
users migrate by leading them to the up-to-date version/doc ?

[Daniel Solano Gomez]

> In order to allow autodoc to consistently present information about
> functions coming and going, I recommend a convention (to be followed
> strictly in clojure itself) of marking namespaces, functions, vars,
> etc. with tags to represent their state:

I like the idea.

> 1) ^{:deprecated "1.2"} would indicate that the namespace/var was
> deprecated in release 1.2.

One question is whether the content ought to be formatted in some
specific way. For example, free text could allowed, such as:

^{:deprecated "Use (foo/bar) instead. To be removed in release 1.3"}

I generally like this, though it makes it harder for tool to interpret.

> 2) ^{:added "1.2"} would indicate that the namespace/var was added in
> release 1.2. (This type of annotation is throughout the python doc and
> is useful when you're trying to write programs that are backwards
> compatible or when you're just trying to scan changes).

Coming from a Java background, I am used to @since. So I would lean
towards :since rather than :added. However, the name is not really
important.

> I think we should:
>
> 1) Implement the deprecation tag immediately (especially for all the
> contrib compatibility stuff like duck-streams) as part of the 1.2
> release. We may also want to update the doc function to show the value
> of this flag.
>
> 2) Add the :added tag to all functions in clojure itself after the 1.2
> release (I'll volunteer to do the first, catch-up pass for this).
>
> In addition to allowing me to generate friendly, consistent
> documentation, these will also be useful for IDEs, program checkers,
> etc.
>
> Does this sound like the right approach to folks?

I think these ideas are good. The key thing is to find the right
balance amongst various factors, such as:

1. Making it easy enough that developers will use the metadata.
2. Making it easy enough for users to read and understand the metadata.
3. Making the metadata easy to parse by tools.

I think the first two are more important than the last.

Sincerely,

Daniel Solano Gómez

[Laurent PETIT]

I've always thought about :since in java as something that could be
filled automatically by tools. Not a clue of how one could do that
easily, though :-)

2010/4/27 Alex Taggart <alex.t...@gmail.com>:

[Stuart Halloway]

In Clojure:

Write a short script that knows about all the namespaces (can use find-
ns stuff in contrib or hard-code it) and creates a map of ns -> all
known symbols in that ns

Go back to the 1.0 release and run the script, creating a
symbols-1-0.clj
Ditto for 1.1 and 1.2.

Check those files in somewhere doc tool can find them.

Should work, no?

Stu

[Laurent PETIT]

guess so

2010/4/27 Stuart Halloway <stuart....@gmail.com>:

[Tom Faulhaber]

Yeah, but getting it back into the source code is important. The is that all the info that autodoc uses be available to all tools.

If a library is important enough that we care about documenting version numbers, we should be thinking hard enough about each public function that we add that the overhead of specifying the metadata field is small. Clojure itself presumably meets that criteria.

A similar easy thing to do would be to add a validation step that makes sure that in a given library, all documented public symbols have a :since tag.

On Tue, Apr 27, 2010 at 1:44 PM, Stuart Halloway <stuart....@gmail.com> wrote:

In Clojure:

Write a short script that knows about all the namespaces (can use find-ns stuff in contrib or hard-code it) and creates a map of ns -> all known symbols in that ns

[Stuart Halloway]

To be clear: I am suggesting that we get the metadata into the code
without writing the metadata by hand in every function.

Stu

[Tom Faulhaber]

Great idea. Autodoc already has the code for collecting symbols and generating a .clj with all of them with a piece of code that runs across the various Clojure versions.

Do we have an idea of how to do the minimal edit to add the metadata back to the source? That sounds like the hardest part of the problem to me.

Based on what I know, I think I'd just do it as an emacs macro once I was able to get a map of symbol-name -> version. :-)

Tom

I'm kind of imagining the

[Stuart Halloway]

Tom,

Let's do it. Rich is happy with the names "deprecated" and "added".
Since you are now busy doing something else, I will take a pass
creating the :added tags.

Stu

[Tom Faulhaber]

Ok, great. I'll throw the code into autodoc to use them.

To unsubscribe from this group, send email to clojure-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/clojure-dev?hl=en.

--
You received this message because you are subscribed to the Google Groups "Clojure Dev" group.
To post to this group, send email to cloju...@googlegroups.com.
To unsubscribe from this group, send email to clojure-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/clojure-dev?hl=en.

[Christophe Grand]

Hi all,

It would be very nice to be able to exploit this metadata with :refer-clojure. in ns declarations.
(:refer-clojure :only [...]) is tedious and :exclude is not futureproof.
I'd like to be able to write (:refer-clojure :as "1.1").

(I have just been bitten by this problem: enlive defines a flatten fn which now conflicts with the flatten newly defined in core.)

Christophe

--
Professional: http://cgrand.net/ (fr)
On Clojure: http://clj-me.cgrand.net/ (en)

[Rich Hickey]

On Apr 29, 2010, at 5:01 AM, Christophe Grand wrote:

> Hi all,
>
> It would be very nice to be able to exploit this metadata
> with :refer-clojure. in ns declarations.
> (:refer-clojure :only [...]) is tedious and :exclude is not
> futureproof.
> I'd like to be able to write (:refer-clojure :as "1.1").
>
> (I have just been bitten by this problem: enlive defines a flatten
> fn which now conflicts with the flatten newly defined in core.)

Interesting. Not sure about :as. :as-of, :as-if :at-rev ...?

It must not become a promise that Clojure can forever emulate its
past, but rather as a limit on newer stuff, if any.

Rich

[Christophe Grand]

http://www.assembla.com/spaces/clojure/tickets/326-add--as-of-option-to-refer

--
Professional: http://cgrand.net/ (fr)
On Clojure: http://clj-me.cgrand.net/ (en)