Document public API with scaladoc

[OlegIlyenko]

No description provided.

[ShawnTalbert]

+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).

[Mironor]

Do you use any scala style guide ?

[OlegIlyenko]

@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 :)

[OlegIlyenko]

@Mironor In general the codebase follows standard scala style guide.

[Mironor]

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).

[OlegIlyenko]

@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.

[ShawnTalbert]

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 notifications@github.com
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
#9 (comment).

[Mironor]

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.

[OlegIlyenko]

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).

[Mironor]

#54

[curtcox]

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/

[ShawnTalbert]

I fear Scala is being abandoned :(

[dave-handy]

Hi guys... yes, scaldi is abandoned due to some unfortunate circumstances. Please see #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!