OpenLayers OpenLayers

Ticket #853 (closed task: fixed)

Opened 1 year ago

Last modified 4 months ago

Remove JSDOC from CLASS_NAME property

Reported by: euzuro Assigned to:
Priority: minor Milestone: 2.5 Release
Component: documentation Version: 2.4
Keywords: Cc:
State:

Description

every CLASS_NAME still has the: 

/** @final @type String */

JSDOC preceding it. I brought this up on the list, and nobody seems to be *not* in favor of ditching it.

Attachments

className.patch (30.5 kB) - added by euzuro on 07/19/07 19:19:29.
remove all instances of the /** @final @type String */
className.Map.RegularPolygon.patch (0.7 kB) - added by fredj on 09/13/07 03:26:11.
853.patch (1.8 kB) - added by fredj on 11/09/07 07:37:15.
Remove JSDOC from CLASS_NAME (again)

Change History

07/19/07 19:19:29 changed by euzuro

  • attachment className.patch added.

remove all instances of the /** @final @type String */

07/19/07 19:22:16 changed by euzuro

  • keywords set to review.

I realize this is only a documentation change and therefore technically does not require a 2nd committer-eye... but this is kind of a giant patch and also a stylistic one and so hey... if i can get some support behind this, it would be great.

all tests pass in ff and ie6

07/22/07 08:33:53 changed by crschmidt

  • keywords changed from review to commit.

Toss it. Sorry I was silent, instead of vocal, about that before.

07/23/07 11:09:33 changed by euzuro

  • keywords deleted.
  • status changed from new to closed.
  • resolution set to fixed.

in with r3787

(follow-up: ↓ 5 ) 07/24/07 19:32:01 changed by tschaub

Post mortem comment: what was wrong with the nice ND style Constant comment?

(in reply to: ↑ 4 ; follow-up: ↓ 10 ) 07/24/07 23:01:58 changed by euzuro

Replying to tschaub:

Post mortem comment: what was wrong with the nice ND style Constant comment?

The general consensus was that commenting those was really just unnecessary: it doesn't particularly help us to have them show up in the ND api docs, and it certainly doesn't help in the actual code itself. Those are really just there for debugging purposes (and ocasionally as a basis for id generation).

09/13/07 03:25:37 changed by fredj

  • status changed from closed to reopened.
  • resolution deleted.

Remove JSDOC from Map and RegularPolygon

09/13/07 03:26:11 changed by fredj

  • attachment className.Map.RegularPolygon.patch added.

09/13/07 06:27:44 changed by crschmidt

  • status changed from reopened to closed.
  • resolution set to fixed.

(In [4256]) Remove class_name jsdoc for consistency, thanks fredj. (Closes #853)

11/09/07 07:37:15 changed by fredj

  • attachment 853.patch added.

Remove JSDOC from CLASS_NAME (again)

11/09/07 07:37:25 changed by fredj

  • status changed from closed to reopened.
  • resolution deleted.

11/09/07 11:23:57 changed by euzuro

  • status changed from reopened to closed.
  • resolution set to fixed.

(In [5157]) remove some stray oldschool jsdoc comments for the CLASS_NAME property. this re-closes the 853 ticket (Closes #853)

(in reply to: ↑ 5 ) 11/09/07 12:53:39 changed by tschaub

Replying to euzuro:

Replying to tschaub:

Post mortem comment: what was wrong with the nice ND style Constant comment?

The general consensus was that commenting those was really just unnecessary: it doesn't particularly help us to have them show up in the ND api docs, and it certainly doesn't help in the actual code itself. Those are really just there for debugging purposes (and ocasionally as a basis for id generation).

For what it's worth, I consider CLASS_NAME to be a critical property of OL objects. Since we can't rely on the constructor property and the instanceof operator isn't useful in all situations, CLASS_NAME is our key for determining what our objects are instances of. Granted, it's a flaky thing to rely on (because we are prone to typos), but I think it should be treated as a first class citizen (tested, documented, etc). Note that none of the vector/geometry code would work without it. And if anybody is interested in object serialization (the context sandbox), that code relies heavily on it.

Anyway, just more post mortem comments.

11/13/07 10:39:50 changed by euzuro

Interesting, I did not know we had code that was dependent on CLASS_NAME. Good to know -- thanks for the explanation!

Do you, however, think we should resuscitate the comments? Seems to me like the only reason to have ND comments there is if we want them to show up in the docs, and I really can't see a good reason for it.

I'm certainly open to being wrong, though... please speak

08/05/08 01:54:49 changed by fredj

(In [7704]) Remove JSDOC from CLASS_NAME property, (see #853)