Source code documentation
Forum rules
READ NOW: L2j Forums Rules of Conduct
READ NOW: L2j Forums Rules of Conduct
-
- Posts: 15
- Joined: Tue Jul 28, 2009 1:33 pm
Source code documentation
I have generated the L2JServer class documentation from the source code so I thought I'd share it all with you. I have it automatically updating when I do a rebuild form the source so it should stay relatively up to date.
API docs
If we were to follow some coding standards and include mandatory doc-block style comments at the top of each class and method it would make this much more useful. They don't take much time to write when you create or change a method so it's well worth it for the time you save trying to figure out how a functions works.
API docs
If we were to follow some coding standards and include mandatory doc-block style comments at the top of each class and method it would make this much more useful. They don't take much time to write when you create or change a method so it's well worth it for the time you save trying to figure out how a functions works.
- Flashy
- Posts: 310
- Joined: Mon Sep 29, 2008 11:49 am
- Location: Germany
Re: Source code documentation
great Job!
tihis helps many new "coder", to learn something about the l2j sturcture..
tihis helps many new "coder", to learn something about the l2j sturcture..
- JIV
- L2j Veteran
- Posts: 1882
- Joined: Sun Jan 06, 2008 8:17 pm
- Location: Slovakia
- Contact:
Re: Source code documentation
amazing work, THX!
- shinomidefuego
- Posts: 122
- Joined: Thu Jun 28, 2007 5:37 pm
- Location: Venezuela
- Contact:
- ThePhoenixBird
- L2j Inner Circle
- Posts: 1857
- Joined: Fri May 27, 2005 5:11 pm
Re: Source code documentation
Excellent work!
This thread deserve a sticky!
This thread deserve a sticky!
- jurchiks
- Posts: 6769
- Joined: Sat Sep 19, 2009 4:16 pm
- Location: Eastern Europe
Re: Source code documentation
Generating with javadoc doesn't really require much of anything...
It is nice of course, but the problem is that l2j code documentation is terrible. There are only few classes that have complete and proper javadoc-style comments, most either have no documentation at all, except @author and, possibly, @version, or have very poor documentation.
Also it would be very hard to write the proper docs for all of them as reading through all those classes/methods just makes you see how badly written l2j actually is. I tried once, and I couldn't stop myself from rewriting most of what I read (I didn't read much though, it's just that much of a thorn in the eye).
It is nice of course, but the problem is that l2j code documentation is terrible. There are only few classes that have complete and proper javadoc-style comments, most either have no documentation at all, except @author and, possibly, @version, or have very poor documentation.
Also it would be very hard to write the proper docs for all of them as reading through all those classes/methods just makes you see how badly written l2j actually is. I tried once, and I couldn't stop myself from rewriting most of what I read (I didn't read much though, it's just that much of a thorn in the eye).
If you have problems, FIRST TRY SOLVING THEM YOURSELF, and if you get errors, TRY TO ANALYZE THEM, and ONLY if you can't help it, THEN ask here.
Otherwise you will never learn anything if all you do is copy-paste!
Discussion breeds innovation.
Otherwise you will never learn anything if all you do is copy-paste!
Discussion breeds innovation.
-
- Posts: 15
- Joined: Tue Jul 28, 2009 1:33 pm
Re: Source code documentation
No, it wasn't that tricky to get javadoc working on th source, it's now part of my build script. In fact I posted it here because I was so surprised that nobody had done it before. It's quite sparse in some places about what a function actually does though it's much easier to skim to find the function you want than the source.
My suggestion of adopting some commenting standards was to help improve this automatically generated docs to the point where it can be really useful to newcomers as well as people more familiar with the source.
I'll try and keep it up to date by rebuilding fairly frequently.
My suggestion of adopting some commenting standards was to help improve this automatically generated docs to the point where it can be really useful to newcomers as well as people more familiar with the source.
I'll try and keep it up to date by rebuilding fairly frequently.
-
- L2j Veteran
- Posts: 99
- Joined: Sun Mar 11, 2007 6:23 pm
Re: Source code documentation
i could never really do smth with this docs in l2j since eclipse is showing the comments atomatically.
Also i belive that code that was hard to write should be hard to read
Also i belive that code that was hard to write should be hard to read
http://code.google.com/p/g3d-editor/
Experienced in the following languages/apis/ides: Java using Eclipse/AWT/Swing/NIO/JNI/Jogl, C/C++11/c++14 using QT/MFC/BOOST/STL/VS2012/VS2013/OpenGL/DirectX, Delphi using Borland, .NET/C# using VS2012/VS2013
Experienced in the following languages/apis/ides: Java using Eclipse/AWT/Swing/NIO/JNI/Jogl, C/C++11/c++14 using QT/MFC/BOOST/STL/VS2012/VS2013/OpenGL/DirectX, Delphi using Borland, .NET/C# using VS2012/VS2013
- jurchiks
- Posts: 6769
- Joined: Sat Sep 19, 2009 4:16 pm
- Location: Eastern Europe
Re: Source code documentation
Surely it wasn't THAT hard to write...
If you have problems, FIRST TRY SOLVING THEM YOURSELF, and if you get errors, TRY TO ANALYZE THEM, and ONLY if you can't help it, THEN ask here.
Otherwise you will never learn anything if all you do is copy-paste!
Discussion breeds innovation.
Otherwise you will never learn anything if all you do is copy-paste!
Discussion breeds innovation.
-
- Posts: 70
- Joined: Mon Jul 20, 2009 4:36 pm
Re: Source code documentation
any advice from where should I start to understand how the server works ?
My goal its to make a console application, and put it to talk with the server.
My goal its to make a console application, and put it to talk with the server.
- delix
- Posts: 11
- Joined: Sun Feb 06, 2011 9:52 pm
- Location: Ukraine, Crimea, Eastern Еurope baby;)
Re: Source code documentation
This is really Great job TomDavidson !!!TomDavidson wrote:I have generated the L2JServer class documentation from the source code so I thought I'd share it all with you. I have it automatically updating when I do a rebuild form the source so it should stay relatively up to date.
API docs
If we were to follow some coding standards and include mandatory doc-block style comments at the top of each class and method it would make this much more useful. They don't take much time to write when you create or change a method so it's well worth it for the time you save trying to figure out how a functions works.
Especially for novices like me
Just keep doing in this way!
I'm interesting in this too. Let us know where and what we need to start with?siulx wrote: any advice from where should I start to understand how the server works ?
My goal its to make a console application, and put it to talk with the server.
Thx.
"Life is what happens to you while you're busy making other plans"
- Sirpaypi
- Posts: 108
- Joined: Mon May 18, 2009 11:51 pm
- Location: Moяocco.
Re: Source code documentation
Please re-upload.
Saying that Java is nice because it works on all OSes is like saying that anal sex is nice because it works on all genders.
-
- Posts: 15
- Joined: Tue Jul 28, 2009 1:33 pm
Re: Source code documentation
Apologies for the broken link, my L2 server died and it was hosted there.
I've rebuild them to pre-Hi5 and talking to people to get them up on here with the rest of the documentation. In the mean time I've uploaded them here: http://www.davidson.me.uk/dev/l2jserver/ and changed the link in my sig.
I've rebuild them to pre-Hi5 and talking to people to get them up on here with the rest of the documentation. In the mean time I've uploaded them here: http://www.davidson.me.uk/dev/l2jserver/ and changed the link in my sig.