From 670ad939c3f90c732942c9deb216e15e63907fff Mon Sep 17 00:00:00 2001
From: Kalle Olavi Niemitalo <kon@iki.fi>
Date: Thu, 23 Nov 2006 23:33:43 +0200
Subject: [PATCH] Bug 846: Comments on the relations between JSClasses and
 functions.

---
 src/ecmascript/spidermonkey/document.c  |  4 ++++
 src/ecmascript/spidermonkey/form.c      | 16 ++++++++++++++++
 src/ecmascript/spidermonkey/location.c  |  6 ++++++
 src/ecmascript/spidermonkey/navigator.c |  1 +
 src/ecmascript/spidermonkey/unibar.c    |  2 ++
 src/ecmascript/spidermonkey/window.c    |  5 +++++
 src/scripting/smjs/action_object.c      |  3 +++
 src/scripting/smjs/bookmarks.c          |  4 ++++
 src/scripting/smjs/cache_object.c       |  3 +++
 src/scripting/smjs/globhist.c           |  4 ++++
 src/scripting/smjs/keybinding.c         |  3 +++
 src/scripting/smjs/view_state_object.c  |  2 ++
 12 files changed, 53 insertions(+)

diff --git a/src/ecmascript/spidermonkey/document.c b/src/ecmascript/spidermonkey/document.c
index cef2aa236..18a6aa174 100644
--- a/src/ecmascript/spidermonkey/document.c
+++ b/src/ecmascript/spidermonkey/document.c
@@ -68,6 +68,7 @@ const JSPropertySpec document_props[] = {
 	{ NULL }
 };
 
+/* @document_class.getProperty */
 static JSBool
 document_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -154,6 +155,7 @@ document_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @document_class.setProperty */
 static JSBool
 document_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -239,6 +241,7 @@ document_write_do(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv,
 	return JS_TRUE;
 }
 
+/* @document_funcs{"write"} */
 static JSBool
 document_write(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -246,6 +249,7 @@ document_write(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rv
 	return document_write_do(ctx, obj, argc, argv, rval, 0);
 }
 
+/* @document_funcs{"writeln"} */
 static JSBool
 document_writeln(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
diff --git a/src/ecmascript/spidermonkey/form.c b/src/ecmascript/spidermonkey/form.c
index 010eaf5b2..d7182c796 100644
--- a/src/ecmascript/spidermonkey/form.c
+++ b/src/ecmascript/spidermonkey/form.c
@@ -120,6 +120,7 @@ static const JSFunctionSpec input_funcs[] = {
 static JSString *unicode_to_jsstring(JSContext *ctx, unicode_val_T u);
 static unicode_val_T jsval_to_accesskey(JSContext *ctx, jsval *vp);
 
+/* @input_class.getProperty */
 static JSBool
 input_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -241,6 +242,7 @@ input_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @input_class.setProperty */
 static JSBool
 input_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -331,6 +333,7 @@ input_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @input_funcs{"blur"} */
 static JSBool
 input_blur(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -339,6 +342,7 @@ input_blur(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 	return JS_TRUE;
 }
 
+/* @input_funcs{"click"} */
 static JSBool
 input_click(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -373,6 +377,7 @@ input_click(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 	return JS_TRUE;
 }
 
+/* @input_funcs{"focus"} */
 static JSBool
 input_focus(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -402,6 +407,7 @@ input_focus(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 	return JS_TRUE;
 }
 
+/* @input_funcs{"select"} */
 static JSBool
 input_select(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -486,6 +492,7 @@ static const JSPropertySpec form_elements_props[] = {
 	{ NULL }
 };
 
+/* @form_elements_class.getProperty */
 static JSBool
 form_elements_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -521,6 +528,7 @@ form_elements_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @form_elements_funcs{"item"} */
 static JSBool
 form_elements_item(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -558,6 +566,7 @@ form_elements_item(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval
 	return JS_TRUE;
 }
 
+/* @form_elements_funcs{"namedItem"} */
 static JSBool
 form_elements_namedItem(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -638,6 +647,7 @@ static const JSFunctionSpec form_funcs[] = {
 	{ NULL }
 };
 
+/* @form_class.getProperty */
 static JSBool
 form_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -745,6 +755,7 @@ form_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @form_class.setProperty */
 static JSBool
 form_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -808,6 +819,7 @@ form_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @form_funcs{"reset"} */
 static JSBool
 form_reset(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -828,6 +840,7 @@ form_reset(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 	return JS_TRUE;
 }
 
+/* @form_funcs{"submit"} */
 static JSBool
 form_submit(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -894,6 +907,7 @@ const JSPropertySpec forms_props[] = {
 	{ NULL }
 };
 
+/* @forms_class.getProperty */
 static JSBool
 forms_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -924,6 +938,7 @@ forms_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @forms_funcs{"item"} */
 static JSBool
 forms_item(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -952,6 +967,7 @@ forms_item(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 	return JS_TRUE;
 }
 
+/* @forms_funcs{"namedItem"} */
 static JSBool
 forms_namedItem(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
diff --git a/src/ecmascript/spidermonkey/location.c b/src/ecmascript/spidermonkey/location.c
index c963a3ffb..8546934bc 100644
--- a/src/ecmascript/spidermonkey/location.c
+++ b/src/ecmascript/spidermonkey/location.c
@@ -63,6 +63,7 @@ const JSFunctionSpec history_funcs[] = {
 	{ NULL }
 };
 
+/* @history_funcs{"back"} */
 static JSBool
 history_back(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -79,6 +80,7 @@ history_back(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval
 	return 2;
 }
 
+/* @history_funcs{"forward"} */
 static JSBool
 history_forward(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -91,6 +93,7 @@ history_forward(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *r
 	return 2;
 }
 
+/* @history_funcs{"go"} */
 static JSBool
 history_go(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -137,6 +140,7 @@ const JSPropertySpec location_props[] = {
 	{ NULL }
 };
 
+/* @location_class.getProperty */
 static JSBool
 location_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -160,6 +164,7 @@ location_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @location_class.setProperty */
 static JSBool
 location_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -187,6 +192,7 @@ const JSFunctionSpec location_funcs[] = {
 	{ NULL }
 };
 
+/* @location_funcs{"toString"}, @location_funcs{"toLocaleString"} */
 static JSBool
 location_toString(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
diff --git a/src/ecmascript/spidermonkey/navigator.c b/src/ecmascript/spidermonkey/navigator.c
index 3a9ead4de..aa0629a95 100644
--- a/src/ecmascript/spidermonkey/navigator.c
+++ b/src/ecmascript/spidermonkey/navigator.c
@@ -75,6 +75,7 @@ const JSPropertySpec navigator_props[] = {
 };
 
 
+/* @navigator_class.getProperty */
 static JSBool
 navigator_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
diff --git a/src/ecmascript/spidermonkey/unibar.c b/src/ecmascript/spidermonkey/unibar.c
index 4dec02064..39620dbd2 100644
--- a/src/ecmascript/spidermonkey/unibar.c
+++ b/src/ecmascript/spidermonkey/unibar.c
@@ -69,6 +69,7 @@ const JSPropertySpec unibar_props[] = {
 };
 
 
+/* @menubar_class.getProperty, @statusbar_class.getProperty */
 static JSBool
 unibar_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -108,6 +109,7 @@ unibar_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_TRUE;
 }
 
+/* @menubar_class.setProperty, @statusbar_class.setProperty */
 static JSBool
 unibar_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
diff --git a/src/ecmascript/spidermonkey/window.c b/src/ecmascript/spidermonkey/window.c
index 0ccfe940b..6ce859bd7 100644
--- a/src/ecmascript/spidermonkey/window.c
+++ b/src/ecmascript/spidermonkey/window.c
@@ -116,6 +116,7 @@ find_child_frame(struct document_view *doc_view, struct frame_desc *tframe)
 }
 #endif
 
+/* @window_class.getProperty */
 static JSBool
 window_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -234,6 +235,7 @@ found_parent:
 
 void location_goto(struct document_view *doc_view, unsigned char *url);
 
+/* @window_class.setProperty */
 static JSBool
 window_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -279,6 +281,7 @@ const JSFunctionSpec window_funcs[] = {
 	{ NULL }
 };
 
+/* @window_funcs{"alert"} */
 static JSBool
 window_alert(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -299,6 +302,7 @@ window_alert(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval
 	return JS_TRUE;
 }
 
+/* @window_funcs{"open"} */
 static JSBool
 window_open(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
@@ -393,6 +397,7 @@ end:
 	return JS_TRUE;
 }
 
+/* @window_funcs{"setTimeout"} */
 static JSBool
 window_setTimeout(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
 {
diff --git a/src/scripting/smjs/action_object.c b/src/scripting/smjs/action_object.c
index 8c4ab9524..49d786855 100644
--- a/src/scripting/smjs/action_object.c
+++ b/src/scripting/smjs/action_object.c
@@ -21,6 +21,7 @@ struct smjs_action_fn_callback_hop {
 	action_id_T action_id;
 };
 
+/* @action_fn_class.finalize */
 static void
 smjs_action_fn_finalize(JSContext *ctx, JSObject *obj)
 {
@@ -29,6 +30,7 @@ smjs_action_fn_finalize(JSContext *ctx, JSObject *obj)
 	if (hop) mem_free(hop);
 }
 
+/* @action_fn_class.call */
 static JSBool
 smjs_action_fn_callback(JSContext *ctx, JSObject *obj, uintN argc, jsval *argv,
                         jsval *rval)
@@ -108,6 +110,7 @@ smjs_get_action_fn_object(unsigned char *action_str)
 
 /*** elinks.action object ***/
 
+/* @action_class.getProperty */
 static JSBool
 action_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
diff --git a/src/scripting/smjs/bookmarks.c b/src/scripting/smjs/bookmarks.c
index 4c76a33d3..699caaa99 100644
--- a/src/scripting/smjs/bookmarks.c
+++ b/src/scripting/smjs/bookmarks.c
@@ -35,6 +35,7 @@ smjs_get_bookmark_generic_object(struct bookmark *bookmark, JSClass *clasp)
 	return NULL;
 };
 
+/* @bookmark_class.finalize, @bookmark_folder_class.finalize */
 static void
 bookmark_finalize(JSContext *ctx, JSObject *obj)
 {
@@ -61,6 +62,7 @@ static const JSPropertySpec bookmark_props[] = {
 
 static JSObject *smjs_get_bookmark_folder_object(struct bookmark *bookmark);
 
+/* @bookmark_class.getProperty */
 static JSBool
 bookmark_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -96,6 +98,7 @@ bookmark_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_FALSE;
 }
 
+/* @bookmark_class.setProperty */
 static JSBool
 bookmark_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -158,6 +161,7 @@ smjs_get_bookmark_object(struct bookmark *bookmark)
 
 /*** bookmark folder object ***/
 
+/* @bookmark_folder_class.getProperty */
 static JSBool
 bookmark_folder_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
diff --git a/src/scripting/smjs/cache_object.c b/src/scripting/smjs/cache_object.c
index 49ec24389..9c6bf3ed4 100644
--- a/src/scripting/smjs/cache_object.c
+++ b/src/scripting/smjs/cache_object.c
@@ -31,6 +31,7 @@ static const JSPropertySpec cache_entry_props[] = {
 	{ NULL }
 };
 
+/* @cache_entry_class.getProperty */
 static JSBool
 cache_entry_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -82,6 +83,7 @@ cache_entry_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_FALSE;
 }
 
+/* @cache_entry_class.setProperty */
 static JSBool
 cache_entry_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -129,6 +131,7 @@ cache_entry_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_FALSE;
 }
 
+/* @cache_entry_class.finalize */
 static void
 cache_entry_finalize(JSContext *ctx, JSObject *obj)
 {
diff --git a/src/scripting/smjs/globhist.c b/src/scripting/smjs/globhist.c
index 51dc91fda..411e14308 100644
--- a/src/scripting/smjs/globhist.c
+++ b/src/scripting/smjs/globhist.c
@@ -13,6 +13,7 @@
 #include "util/memory.h"
 
 
+/* @smjs_globhist_item_class.finalize */
 static void
 smjs_globhist_item_finalize(JSContext *ctx, JSObject *obj)
 {
@@ -34,6 +35,7 @@ static const JSPropertySpec smjs_globhist_item_props[] = {
 	{ NULL }
 };
 
+/* @smjs_globhist_item_class.getProperty */
 static JSBool
 smjs_globhist_item_get_property(JSContext *ctx, JSObject *obj, jsval id,
                                 jsval *vp)
@@ -86,6 +88,7 @@ smjs_globhist_item_get_property(JSContext *ctx, JSObject *obj, jsval id,
 	return JS_FALSE;
 }
 
+/* @smjs_globhist_item_class.setProperty */
 static JSBool
 smjs_globhist_item_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -157,6 +160,7 @@ smjs_get_globhist_item_object(struct global_history_item *history_item)
 }
 
 
+/* @smjs_globhist_class.getProperty */
 static JSBool
 smjs_globhist_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
diff --git a/src/scripting/smjs/keybinding.c b/src/scripting/smjs/keybinding.c
index 26c04bf2d..6087d9c86 100644
--- a/src/scripting/smjs/keybinding.c
+++ b/src/scripting/smjs/keybinding.c
@@ -13,6 +13,7 @@
 #include "scripting/smjs/elinks_object.h"
 #include "util/memory.h"
 
+/* @keymap_class.getProperty */
 static JSBool
 keymap_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -58,6 +59,7 @@ smjs_keybinding_action_callback(va_list ap, void *data)
 	return EVENT_HOOK_STATUS_LAST;
 }
 
+/* @keymap_class.setProperty */
 static JSBool
 keymap_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -127,6 +129,7 @@ keymap_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_FALSE;
 }
 
+/* @keymap_class.finalize */
 static void
 keymap_finalize(JSContext *ctx, JSObject *obj)
 {
diff --git a/src/scripting/smjs/view_state_object.c b/src/scripting/smjs/view_state_object.c
index dfab9542f..a93915958 100644
--- a/src/scripting/smjs/view_state_object.c
+++ b/src/scripting/smjs/view_state_object.c
@@ -31,6 +31,7 @@ static const JSPropertySpec view_state_props[] = {
 	{ NULL }
 };
 
+/* @view_state_class.getProperty */
 static JSBool
 view_state_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {
@@ -59,6 +60,7 @@ view_state_get_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 	return JS_FALSE;
 }
 
+/* @view_state_class.setProperty */
 static JSBool
 view_state_set_property(JSContext *ctx, JSObject *obj, jsval id, jsval *vp)
 {