Need more documentation for writing scripts

Submitted by vr2 on Sat, 05/11/2013 - 07:47

Forums:

Hi,

I'm trying to write a script for a complex site login, but I'm having problems getting it to work due to the lack of documentation. I read the post about how to create a script at http://xnotifier.tobwithu.com/dp/node/7, but it covers very little. When I look at some of the example scripts, they are using things that have no explaination or documentation.

Some of the scripts for download have a function that looks like "process(aData,aHttp)". What is calling this function? What is supplied in aHttp? Where is it documented?

Many of the process() functions in the scripts use case statements with labels like ST_PRE, ST_PRE_RES, ST_LOGIN, etc. What are these? What do they mean? Where are they documented?

What does the getIconURL() function do? What is calling it? Where is it documented?

What does the getIconPage() function do? What is calling it? Where is it documented?

What does the checkLogin() function do in the gplus.js script? What is calling it? Where is it documented?

What does the getViewURL() function do in the vodafone.js script? What is calling it? Where is it documented?

What does the getData() function do in the vodafone.js script? What is calling it? Where is it documented?

In the init() function, some scripts set variables for initState, viewDomain, cookieDomain, logoutURL, and baseURL. What are these variables for? Where are they documented?

The top of some scripts set variable supportMulti to true. What does that do? Where is it documented?

I'd appreciate any help that you can provide.

RpD

Sat, 05/11/2013 - 09:28

I'm not trying to be belligerent to your post, but trying to show some respect for the author's work.

Repeating 'Where is it documented' is a bit of a bludgeon, don't you think?
Perhaps that's due to some frustration? Just wondering if you have done much programming?
All I had to do was google:  x-notifier code
You can see "View the source" links here:  https://addons.mozilla.org/En-us/firefox/addon/xnotifier/versions
....I don't know if that's everything, or what.

I could be wrong, but I think the GNU requirement is to share the code... not provide full documentation of everything.
The author has some rights to his work, and protection of it.  Well-versed programmers should be able to decipher that which GNU requires GNU programmers to provide, I'm guessing.

Finally, the author will very likely create your script if you would share a test account with him at xndevel@gmail.com

I'd agree that complicated scripts are very difficult to write, for casual coders, with the level of information available, but again... the author provides a service of creating scripts.  I'm not sure we can rightfully -demand- that he provide a full course of documentation and instruction of script programming, although some further basic guidance of the process would be nice.
I think writing the complex scripts take a skill set which is beyond the casual or beginning programmer... most likely, it requires a somewhat advanced skill set, at about the developer level... and those with such skills would probably be able to figure out the complex scripting without documentation.  Again, it would be nice for the author to provide a better basic introduction for simple scripts, step by step... but at some point, the aspiring script writer must have a high level of programming skill and I'm guessing they wouldn't need more than the code to analyze. I haven't looked at/analyzed the code that's been provided, though.

Still, the author provides a script-writing service.

 Good luck with your requests though... and hoping the author has the time to provide the extra instruction/documentation.

vr2

Sat, 05/11/2013 - 15:49

Hi RpD. Thanks for responding. I apologize for the tone of my post. I didn't intend for that phrase to be repeated. I was doing a lot of copying, pasting, and editing on my message while I researched different scripts and examined the extension's source code. My wife was bugging me to hurry up so we could go to dinner with her parents and I posted and ran without proofreading.

Regarding the rest of my post, it was not directed towards tobwithu but towards the whole community here on the forums. If I only wanted to address tobwithu, I would have emailed him instead of posting here. tobwithu isn't the only person who has written scripts. Maybe someone else on the forum knows about those items and can share their knowledge to the benefit of everyone here.

One of the great things about X-notifier is that it's extensible and the author encourages people to take advantage of that. However, enough documentation needs to be provided on how to extend it. You seem to think I'm asking for a tutorial. I'm not. I'm asking for basic documentation on the API. What variables exist and functions are available, what do they do, and what data do they accept and return.

I can't provide an account on the system in question for technical and legal reasons. Even if I could, if I get tobwithu to write the script for me, then it takes time away from other things he might want to do, robs me of the chance to improve my JavaScript skills, and continues to keep the knowledge of how to extend X-notifer isolated to tobwithu. That's not a good thing for the X-notifier community or tobwithu.

We need to be sharing knowledge about how to extend X-notifier so that other people can write scripts and contribute them to the script library if applicable. If tobwithu or another script author would spend the same amount time he would use writing one script to document the API, then it would lower the barrier to entry considerably for other script authors.

Without a documented API, the only recourse is to examine the extension's source code and try to figure things out. It's not a large code base and not impossible to do, but it can take a lot of time and effort. That investment increases quite a bit if you don't know JavaScript or Firefox internals. Multiply that time and effort by everyone who is trying to write a script that needs more functionality than what http://xnotifier.tobwithu.com/dp/node/7 provides and there will be a lot of wasted man-hours.

So, I hope that tobwithu and others with this knowledge will be willing to take a moment and share it with the community. We'll all benefit from their generosity.

RpD

Sat, 05/11/2013 - 18:55

That would be nice if some others wish to provide documentation on tobwithu's programming >;} ...a little irony there perhaps. There is a little encouragement I suppose, for scriptwriting... but like you, I guess I'm not seeing -that- much encouragment... or there might be greater documentation. I sense a little reticence to do so by admin, for product protection ("knowledge isolated to tobwithu") or... just not investing the tedious time/effort it requires. But script requests/writing time seem to be expected.

I'm not sure I've seen much additional documentation effort provided for other add-on/donationware. However, as you mention, some others have made the effort to develop scripts, so I've assumed a certain skillset finds that possible from the source or experience with webmail... but not a trivial task. Javascript, etc., experience seems expected for the script writer to have. I suppose it was the tone of the initial post, and past requests from others, that led me to think some instruction was demanded besides documentation.

Good luck with reponses... such documentation would be educational. ;)

 

tobwithu's picture

tobwithu

Sat, 05/11/2013 - 22:02

I agree that more documentation for writting script is needed.
However, the documentation is not easy because

  1. API is not fixed yet. It can be changed frequently.
  2. Writting script is not easy, because webmail sites are getting more complicated.
  3. I don't have enough time.

I will do it when script API is mature enough.