scaldi
scaldi copied to clipboard
scaldi
Document public API with scaladoc
+1 I appreciate that this is an open source project, but I'm appalled at the utter lack of comments (and especially lack of scaladoc).
@ironside At some point it was clear that scaldi needed a good and extensive documentation. I decided to do write more higher level documentation and some tutorials. That was time when I created this page: http://scaldi.org/learn/. It took quite some time and effort, but I believe that this kind of documentation is often more valuable than scaladoc mostly because it gives a good explanation behind the concepts that library introduces and gives more higher-level description of all components and how they work together.
That said, I still believe that scaladoc is important, so it's definitely something I would like to do in future. I just need to find some time to do it... it's a little bit tedious job :)
I would really like to provide some contribution (at least as scaladocs for classes/traits/methods) but I cannot wrap my mind around the code (too many things i one file, no schema/model of the main architecture). If you could provide a form of flow chart for some of the main use cases from http://scaldi.org/learn/ it would be really helpful (as your documentation explains the usage, but not the internals).
@Mironor Great, glad to hear this! Sure, would be happy to do this. Just give me some time and I will think of something. I think It would be really nice to have this kind of internals-overview in any case.
Your "learning" web site is beautiful, and I can see it took quite some time.
Ironically perhaps, my expectation for scaladocs were even greater after I saw all the nice documentation you created on the web site...
However, to be honest Scaldi didn't start making sense to me until I looked at an complete example that showed things end to end. The partial examples you have in the web site documentation would be great as examples in scaladoc as well. As
I use IntelliJ IDEA for hacking on Scala; just press CTRL+Q and get nice formatted, detailed help in real time (if the scaladocs are there). That would surely have sped up my learning curve for Scaldi. Perhaps even more important is the reference it provides months from now when I've forgotten some of the detail :)
I agree with Alexandre in that the web site would be more effective if it provided an initial (probably grpaphical?) overview of how the different pieces fit together in addition to introducing the individual components.
On Thu, Feb 19, 2015 at 11:21 AM, Oleg Ilyenko [email protected] wrote:
@ironside https://github.com/ironside At some point it was clear that scaldi needed a good and extensive documentation. I decided to do write more higher level documentation and some tutorials. That was time when I created this page: http://scaldi.org/learn/. It took quite some time and effort, but I believe that this kind of documentation is often more valuable than scaladoc mostly because it gives a good explanation behind the concepts that library introduces and gives more higher-level description of all components and how they work together.
That said, I still believe that scaladoc is important, so it's definitely something I would like to do in future. I just need to find some time to do it... it's a little bit tedious job :)
— Reply to this email directly or view it on GitHub https://github.com/scaldi/scaldi/issues/9#issuecomment-75117570.
Hi Oleg, I'm trying to find my way into Scaldi's code, do you have anything against scaladoc/javadoc? I could start this Documentation issue with documenting methods/class/traits.
I would definitely appreciate it! I feel that having proper scaladocs would be a great improvement. Unfortunately I haven't did it yet, but definitely wanted to do it at some point. I even publish scaladocs to the gh-pages already (they are not versioned yet, but it should be pretty easy to setup).
scaldi.org has been abandoned. At least some of the content is available from archive.org. https://web.archive.org/web/20190910133453/http://scaldi.org/learn/
Hi guys... yes, scaldi is abandoned due to some unfortunate circumstances. Please see https://github.com/scaldi/scaldi/issues/81 for details. My company is quite invested in scaldi so we've created a fork that we intend to maintain, although getting the docs online again isn't really a goal. You can see them in web archive or the source files for the docs should also still be available at https://github.com/scaldi/scaldi-website
Scala is definitely not being abondoned!
