scaladoc for salat?

[Brian]

Maybe I'm just having a google-fail here, but where do I find the scaladoc documentation for the classes in salat?

[rktoomey]

Hi Brian,

Salat doesn't have much Scaladoc right now. I will add it at some
point, but honestly, you're the first person ever to ask!

However, Salat does have a lot of documentation:
* comments in the code (source code is published and you can use your
IDE to click through)
* an extensive test suite of specs you can look at on Github (https://
github.com/novus/salat) or check out and run
* a growing wiki that I am working to update right now, at
https://github.com/novus/salat/wiki

Is there a reason you wanted Scaladoc specifically?

Best,
Rose

[Radzislaw Galler]

+1 for scaladoc

On Tuesday, April 24, 2012 1:52:46 PM UTC+2, rktoomey wrote:

Hi Brian,

Salat doesn't have much Scaladoc right now.  I will add it at some
point, but honestly, you're the first person ever to ask!

That's probably because he's the first one not afraid of asking about obvious things.

 

However, Salat does have a lot of documentation:
* comments in the code (source code is published and you can use your
IDE to click through)
* an extensive test suite of specs you can look at on Github (https://
github.com/novus/salat) or check out and run
* a growing wiki that I am working to update right now, at
https://github.com/novus/salat/wiki

Is there a reason you wanted Scaladoc specifically?

I know that real programmers don't write documentation. They write self-documenting code, but:

1. Scaladoc has a nice time-saving ability to filter on-line class names while searching. 
   
2. Clicking through the code should be the last resort - not the first. I don't want to be a salat developer. I want to write my own code using salat. All in all it's a great library.
3. If the code was well commented it would be easy to make it scaladoc capable.
4. I don't use ScalaIDE but it most probably it takes advantage of well documented libraries by displaying hints with documentation while hovering over a symbol.

I got frustrated by searching again a piece of advice (i.e. documentation in the cloud) I saw but don't remember where. Please consider adding answers in this forum marked with 'thanks that was helpful' to the wiki. 

For example right now I try to find the definition of ChildCollection. Clicking through the code on github failed. I have to download the code and search it locally with a little help from my grep. With scaladoc at hand I wouldn't have to do it. I'm aware that this particular class is covered somehow in the wiki but it takes me about 10 clicks to get to the source. With scaladoc it'd take me a few keystrokes and one click.

Cheers,

Rajish

[rktoomey]

Sorry, Rajish,

I am working on Scaladoc but it is a tedious process. I don't enjoy
type type typing great swaths of Scaladoc boilerplate, and there are
no style tools to lint my Scaladoc comments.

Typesafe's own documentation on how to write Scaladoc has a long way
to go toward providing clear examples of how to document things like
curried functions, or how to use @tparam to provide anything other
than completely obvious information. Not to mention how much I don't
enjoy trying to remember in which cases I should be using the subset
of supported Markdown instead of inline HTML tagging. Sun's Javadoc
style guide left me with no confusion whatsoever as to how I should
format things. Scaladoc regularly leaves me trawling Scala source
code.

So I do disagree that clicking through to the code should be a last
resort, but I will provide Scaladoc as soon as I have world enough and
time. I promise that I am working on it.

In the meantime, can't your editor use the published source jar for
class and method signatures? Child collections are indeed documented
on the wiki, available in one click from the main wiki page:
https://github.com/novus/salat/wiki/ChildCollection

Best,
Rose

P.S. I have never seen a "Thanks, that was helpful" marking on the
Google groups interface?

On May 12, 7:55 pm, Radzislaw Galler <gradzis...@gmail.com> wrote:
> +1 for scaladoc
>
> On Tuesday, April 24, 2012 1:52:46 PM UTC+2, rktoomey wrote:
>
> > Hi Brian,
>
> > Salat doesn't have much Scaladoc right now.  I will add it at some
> > point, but honestly, you're the first person ever to ask!
>
> That's probably because he's the first one not afraid of asking about
> obvious things.
>
> > However, Salat does have a lot of documentation:
> > * comments in the code (source code is published and you can use your
> > IDE to click through)
> > * an extensive test suite of specs you can look at on Github (https://
> > github.com/novus/salat) or check out and run
> > * a growing wiki that I am working to update right now, at
> >https://github.com/novus/salat/wiki
>
> > Is there a reason you wanted Scaladoc specifically?
>
> I know that real programmers don't write documentation. They write
> self-documenting code, but:
>

>    1. Scaladoc has a nice time-saving ability to filter on-line class names
>    while searching.
>    2. Clicking through the code should be the last resort - not the first. I

>    don't want to be a salat developer. I want to write my own code using
>    salat. All in all it's a great library.

>    3. If the code was well commented it would be easy to make it scaladoc
>    capable.
>    4. I don't use ScalaIDE but it most probably it takes advantage of well

[rktoomey]

Thanks, Kheraud, I am working on the scaladoc.

Although incomplete for salat-core, I am publishing scaladoc for 2.9.1
and 2.9.2 now (due to https://issues.scala-lang.org/browse/SI-4284, no
scaladoc for 2.8.1).

Best,
Rose

On Jun 21, 9:31 am, Karim Heraud <kher...@gmail.com> wrote:
> +1 for scaladoc,
>
> No matter how detailed your scaladoc is. Just providing the list of methods
> and fields for each class and object would be usefull.
>
> You are right, the wiki and test codes are great but it's hard to sail into
> the code when you try to do something "out of the way".
>
> Thanks again for your realy great work !
>
> Kheraud