Source Code Documentation

[crash-dive]

Is there any value in creating something which better explains how etherpad-lite works from a developer standpoint? There is very little documentation on the etherpad-lite source code which mean trying to understand how it works can be very hard and tends to involve (alteast for me) lots of break points and moving around the call stack to try and understand how everything happens. The node.js server code is easier to understand, but the ACE editor is difficult to say the least.

It would be nice to hear from other people who have been trying to understand the code to know if they feel the same way.

I know people have differing opinions on source code documentation, for example a friend once said to me if you need to document your source code you need to rewrite it because it is not clear. I have some spare time at the moment so I was planning to read through and get a much better understanding of how etherpad-lite works and as I do so I will make notes. Would it be a good idea if I made notes with a view to creating documentation which could be published or even just something less compressive that could serve as an introduction to the code base for new developers?

[JohnMcLear]

This would be great, I was also thinking it would be great if some folks put together walkthroughs of how to change settings, move things about. I was thinking about making some showing how I debug some issues and fix them and then push the changes to github.. Maybe at some point I will still do that.. Just a case of finding time ;\

-----Original Message-----
From: Jonathon Smith [mailto:reply@reply.github.com]
Sent: 02 December 2011 01:17
To: John McLear
Subject: [etherpad-lite] Source Code Documentation (#259)

Is there any value in creating something which better explains how etherpad-lite works from a developer standpoint? There is very little documentation on the etherpad-lite source code which mean trying to understand how it works can be very hard and tends to involve (alteast for me) lots of break points and moving around the call stack to try and understand how everything happens. The node.js server code is easier to understand, but the ACE editor is difficult to say the least.

It would be nice to hear from other people who have been trying to understand the code to know if they feel the same way.

I know people have differing opinions on source code documentation, for example a friend once said to me if you need to document your source code you need to rewrite it because it is not clear. I have some spare time at the moment so I was planning to read through and get a much better understanding of how etherpad-lite works and as I do so I will make notes. Would it be a good idea if I made notes with a view to creating documentation which could be published or even just something less compressive that could serve as an introduction to the code base for new developers?

---

Reply to this email directly or view it on GitHub:
https://github.com/Pita/etherpad-lite/issues/259
This email and its attachments may be confidential and are intended solely for the use of the individual to whom it is addressed. Any views or opinions expressed are solely those of the author and do not necessarily represent those of the organisation from which this email originated. If you are not the intended recipient of this email and its attachments, you must take no action based upon them, nor must you copy or show them to anyone. Please contact the sender if you believe you have received this email in error. This email was sent by School Email - Safe Webmail and Hosted Email for Schools

[Wikinaut]

+1

[yadutaf]

I completely aggree and can help with it since i'm starting to understand well the rendering/editing code

[Pita]

Adding Documentation in the source code is always appreciated. I think its also a good idea to add a "how to debug" page to the wiki (instead of improving the section in the readme all the time)

[crash-dive]

Just an update on this I have been reading and getting a better understanding on how everything works on the editor side of things. I will try and writing something that explains the structure and post it and we will see if anyone thinks it is helpful. And even if is is not it will have helped me.

Also as I am reading the comments a lot I think I will make a note of the typos in the comments and at the end submit a pull to fix them. For example there have been a few times I thought Yoda wrote them: "if we haven't recieved the clientVars yet, then this message should it be"

[JohnMcLear]

Jonathon. Did you see the video I made?

Jonathon Smith reply@reply.github.com wrote:

Just an update on this I have been reading and getting a better understanding on how everything works on the editor side of things. I will try and writing something that explains the structure and post it and we will see if anyone thinks it is helpful. And even if is is not it will have helped me.

Also as I am reading the comments a lot I think I will make a note of the typos in the comments and at the end submit a pull to fix them. For example there have been a few times I thought Yoda wrote them: "if we haven't recieved the clientVars yet, then this message should it be"

---

Reply to this email directly or view it on GitHub:
https://github.com/Pita/etherpad-lite/issues/259#issuecomment-3086864
This email and its attachments may be confidential and are intended solely for the use of the individual to whom it is addressed. Any views or opinions expressed are solely those of the author and do not necessarily represent those of the organisation from which this email originated. If you are not the intended recipient of this email and its attachments, you must take no action based upon them, nor must you copy or show them to anyone. Please contact the sender if you believe you have received this email in error. This email was sent by School Email - Safe Webmail and Hosted Email for Schools

[Pita]

May the Force be with you! ;)

[JohnMcLear]

Hehe

Peter 'Pita' Martischka reply@reply.github.com wrote:

May the Force be with you! ;)

---

Reply to this email directly or view it on GitHub:
https://github.com/Pita/etherpad-lite/issues/259#issuecomment-3086913
This email and its attachments may be confidential and are intended solely for the use of the individual to whom it is addressed. Any views or opinions expressed are solely those of the author and do not necessarily represent those of the organisation from which this email originated. If you are not the intended recipient of this email and its attachments, you must take no action based upon them, nor must you copy or show them to anyone. Please contact the sender if you believe you have received this email in error. This email was sent by School Email - Safe Webmail and Hosted Email for Schools

[JohnMcLear]

https://github.com/ether/etherpad-lite/wiki is your friend.

[monkey-pawan]

Hi JohnMcLear, I couldn't find the link to the video you mentioned above. Please share it, it will be a great help to me to debug how it is working and how can I tweak things as per my requirement.