Looks great. What about putting a hyperlink to the Swiki page for this class comment( assuming that page is up-to-date ), within the class comment?
-----Original Message----- From: Eddie Cottongim [mailto:cottonsqueak@earthlink.net] Sent: Thursday, February 27, 2003 11:36 AM To: squeak-dev@lists.squeakfoundation.org Subject: [ENH][DOC] MorphClassComment-efc
Eddie
from preamble:
"Change Set: MorphClassComment-efc Date: 26 February 2003 Author: Eddie Cottongim
Extended Class Comment for Morph. Thanks to everyone who helped review the draft version!!"!
I had really only intended the swiki page to be a temporary work area. But I do like the idea of some kind of linkage between internal and external docs.
It would be nice if there was a way for the swiki to directly reflect the comments in the image (like javadoc but more dynamically bound), have a way to annotate them, and provide a way that people could harvest updated comments to go into the image. Something like, "show me all the class comments people have annotated/updated since #5183", and the harvester would pick the ones he/she thought were improvements for inclusion with the image. --I don't think you'd want the new comments to go in the image directly/automatically. Too easy for junk to get in that way. --Need to work out the semantics of what happens when the image comment is updated: Probably the comment text would be updated, but old annotations would stay.
Maybe someone did that already. Just an idea.
Eddie
----- Original Message ----- From: "Brent Vukmer" bvukmer@blackboard.com To: "The general-purpose Squeak developers list" squeak-dev@lists.squeakfoundation.org Sent: Thursday, February 27, 2003 11:38 AM Subject: RE: [ENH][DOC] MorphClassComment-efc
Looks great. What about putting a hyperlink to the Swiki page for this class comment( assuming that page is up-to-date ), within the class comment?
I guess I've mentioned this before, but one simple solution would be to have an automatic link of some sort (or perhaps a menu item) from the class comment in the Squeak browser to open scamper on a corresponding swiki page about the class. This way, the swiki page could have more recent class comments if available, easily editable by anyone, as a sort of backup to the class comment in the image (which as we know is often missing completely). And this backup comment would be easily accessible from the class browser.
However, we'd need a reliable way to specify a swiki page based on its name. Something like http://minnow.cc.gatech.edu/squeak?page=Morph should access the page "Morph" on the swiki. Right now, you can try something like http://minnow.cc.gatech.edu/squeak/morph but it doesn't work reliably (as in this case).
I'm submitting this an an official ComSwiki enhancement request this time, if anyone feels like adding this feature. :-)
- Doug Way
Eddie Cottongim wrote:
I had really only intended the swiki page to be a temporary work area. But I do like the idea of some kind of linkage between internal and external docs.
It would be nice if there was a way for the swiki to directly reflect the comments in the image (like javadoc but more dynamically bound), have a way to annotate them, and provide a way that people could harvest updated comments to go into the image. Something like, "show me all the class comments people have annotated/updated since #5183", and the harvester would pick the ones he/she thought were improvements for inclusion with the image. --I don't think you'd want the new comments to go in the image directly/automatically. Too easy for junk to get in that way. --Need to work out the semantics of what happens when the image comment is updated: Probably the comment text would be updated, but old annotations would stay.
Maybe someone did that already. Just an idea.
Eddie
----- Original Message ----- From: "Brent Vukmer" bvukmer@blackboard.com To: "The general-purpose Squeak developers list" squeak-dev@lists.squeakfoundation.org Sent: Thursday, February 27, 2003 11:38 AM Subject: RE: [ENH][DOC] MorphClassComment-efc
Looks great. What about putting a hyperlink to the Swiki page for this class comment( assuming that page is up-to-date ), within the class comment?
I like the idea, but I think there should be a separate "documentation" Swiki used for this purpose. This way, we could easily change out the Swiki backend in favor of something that enables documentation updates to feed back into the update stream.
The class comment only needs to have a link at the top that reads "Search for online documentation" (or similar). That link would take you to the documentation Swiki and search for (or create) a page for class documentation.
- Stephen
Doug Way wrote:
I guess I've mentioned this before, but one simple solution would be to have an automatic link of some sort (or perhaps a menu item) from the class comment in the Squeak browser to open scamper on a corresponding swiki page about the class. This way, the swiki page could have more recent class comments if available, easily editable by anyone, as a sort of backup to the class comment in the image (which as we know is often missing completely). And this backup comment would be easily accessible from the class browser.
However, we'd need a reliable way to specify a swiki page based on its name. Something like http://minnow.cc.gatech.edu/squeak?page=Morph should access the page "Morph" on the swiki. Right now, you can try something like http://minnow.cc.gatech.edu/squeak/morph but it doesn't work reliably (as in this case).
I'm submitting this an an official ComSwiki enhancement request this time, if anyone feels like adding this feature. :-)
- Doug Way
Eddie Cottongim wrote:
I had really only intended the swiki page to be a temporary
work area.
But I do like the idea of some kind of linkage between internal and external docs.
It would be nice if there was a way for the swiki to
directly reflect
the comments in the image (like javadoc but more
dynamically bound),
have a way to annotate them, and provide a way that people could harvest updated comments to go into the image. Something
like, "show
me all the class comments people have annotated/updated
since #5183",
and the harvester would pick the ones he/she thought were
improvements
for inclusion with the image. --I don't think you'd want the new comments to go in the image directly/automatically. Too
easy for junk
to get in that way. --Need to work out the semantics of
what happens
when the image comment is updated: Probably the comment text would be updated, but
old annotations
would stay.
Maybe someone did that already. Just an idea.
Eddie
----- Original Message ----- From: "Brent Vukmer" bvukmer@blackboard.com To: "The general-purpose Squeak developers list" squeak-dev@lists.squeakfoundation.org Sent: Thursday, February 27, 2003 11:38 AM Subject: RE: [ENH][DOC] MorphClassComment-efc
Looks great. What about putting a hyperlink to the Swiki page for this class comment( assuming that page is up-to-date ), within the class comment?
On Fri, Feb 28, 2003 at 11:02:03AM -0500, Stephen Pair wrote:
I like the idea, but I think there should be a separate "documentation" Swiki used for this purpose. This way, we could easily change out the Swiki backend in favor of something that enables documentation updates to feed back into the update stream.
What about http://sqdb.squeak.info ?
o Description: sqdb is an open database of class and method comments for Squeak. Through (proposed) modifications to the Squeak browser, developers can easily examine and submit new entries to the database of documentation. This system is not meant to replace high level documentation, but rather to allow the quick and painless distribution of class and method comments among Squeak users. o Author: Duane Maxwell
Marcus Denker marcus@ira.uka.de wrote:
What about http://sqdb.squeak.info ?
o Description: sqdb is an open database of class and method comments for Squeak. Through (proposed) modifications to the Squeak browser,
Is anyone up for making some changes to the browsers to work with this? I'd suggest making some attempt to check what's on the db before writing any new entry and perhaps allowing a nice merge-the-best-bits attempt. For anyone with some socket/http knowledge it ought not be too hard and it would be very helpful in the push towards some serious class/method commentary.
tim
squeak-dev@lists.squeakfoundation.org
-
Brent Vukmer -
Doug Way -
Eddie Cottongim -
Marcus Denker -
Stephen Pair -
Tim Rowledge