a proposal to simplify and clean up Scaladoc

Having scaladoc that is extremely integrated with the code doesn’t seem like a good thing to me. The current system keeps the documentation and code slightly separated which reduces clutter in the code itself while still allowing the documentation to be “near” the code for easier maintenance. On the other hand I’m the sort of person who doesn’t mind maintaining documentation in a totally separate file (and there are reasons why that is sometimes better) so, for example, duplicating parameter names in the documentation isn’t a problem for me. Anyway it seems like the scaladoc tool could warn about inconsistent parameter names along with similar things.

A specific concern about your example: comments at the top of the class body look like comments about the class constructor to me, not the class as a whole. Maybe the difference is subtle but it seems like an important distinction. Also your comment attached to the package looks like it could be a comment about your import list. I guess I’m just used to documentation appearing before the thing it documents rather than after it.

Peter

From: scala-debate [at] googlegroups [dot] com [mailto:scala-debate [at] googlegroups [dot] com] On Behalf Of Russ Paielli
Sent: Tuesday, December 13, 2011 23:46
To: scala-debate
Subject: [scala-debate] a proposal to simplify and clean up Scaladoc

I would like to propose a SIP to simplify and clean up Scaladoc. The

simplest way to explain it is to start with an example of a short Scala

source file that illustrates it:

/***********************************************************************

This file is an example to illustrate my proposal for simplifying and

cleaning up Scaladoc. Not surprisingly, a comment at the top of the file

is for the top-level documentation of the file. The particular form of

comment delimiter is not important. If several separate comments are

provided at the top of the file, they could simply be concatenated into

one documenation string.

************************************************************************/

package example

/* A comment of any form immediately following a package clause applies

to that package. If the whole file is one package, the top-level comment

can either precede or follow the package clause. */

import whatever.something

class Example ( // optional brief comment about the class here

    val foo: String, // comment about foo here

    val bar: Int = 1, // a place to get beer and booze

    val bat: Boolean = false // hits a ball

    ) {

    /* The top of the class body is the logical place for a more

    detailed description of the class. Typically, if a comment is put

    here, there would be no comment on the class line above, but if

    comments are provided in both places, they could simply be

    concatenated. */

    def method( // optional brief comment about the method here

        x: Double, // explain x here

        y: Double, // explain y here

        z: Double /* here is an example of a longer comment

            that requires two lines */

            // you can also use this form for additional lines

        ): Double = {

        /* The top of the method body is the logical place for a more

        detailed description of the method if necessary. */

        bar * x * y

        }

    }

<end of file>

There you have it. Notice how much cleaner and better integrated into

the source code this format is compared to the current gaudy Scaladoc

format. It eliminates lots of redundant typing and reading. It also

eliminates any possibility of inconsistency in the argument names/types

between Scaladoc and the actual code. That will also simplify

maintanence by preventing the introduction of inconsistency when

arguments are added, removed, or modified in any way.

For rare cases in which the programmer does not wish to have a

particular comment included in Scaladoc, a simple signaling convention

could be used, such as starting the comment with "///" or "//-".

By the way, I am not suggesting that the current Scaladoc format should

be eliminated. I wouldn't complain if it were deprecated, but I

certainly won't push for that. It should be maintained for backward

compatibility, and both formats should be allowed.

A separate but related proposal (which will be a separate SIP) is what I

call comma inference. It's similar to semicolon inference, but it

applies to class/method/function arguments. So for example I should be

allowed to write this:

class Example ( // optional brief comment about the class here

    val foo: String // comment about foo here

    val bar: Int = 1 // a place to get beer and booze

    val bat: Boolean = false // hits a ball (or misses)

    ) {

That's cleaner, and it eliminates the inconsistency of requiring a comma

for all but the last argument, which causes nuisance errors when adding,

removing, or rearranging arguments. (To eliminate any possible

ambiguity, it should perhaps apply only if every argument is on a

separate line.)

--Russ P.

--
http://RussP.us

On Dec 14, 3:40 am, "Peter C. Chapin" wrote:
> Having scaladoc that is extremely integrated with the code doesn't seem like
> a good thing to me. The current system keeps the documentation and code
> slightly separated which reduces clutter in the code itself while still
> allowing the documentation to be "near" the code for easier maintenance. On
> the other hand I'm the sort of person who doesn't mind maintaining
> documentation in a totally separate file (and there are reasons why that is
> sometimes better) so, for example, duplicating parameter names in the
> documentation isn't a problem for me. Anyway it seems like the scaladoc tool
> could warn about inconsistent parameter names along with similar things.

Peter,

I don't see how you can claim with a straight face that the current
Scaladoc format "reduces clutter." Maybe it's just all those
asterisks, but it looks like nothing but clutter to me! And having it
outside the documented class or function just doesn't seem quite right
to me.

I see nothing wrong with separate doc files either in some cases, but
I would use those for more detailed documentation to supplement, not
replace, what appears in Scaladoc.

I find the duplication of argument names and types in Scaladoc to be
almost offensive. It goes against the fundamental principle of
avoiding duplication of function in general to avoid divergence and
inconsistency. Think about it. Every time someone changes the
arguments of a class/method/function in any way, he needs to go up and
make the corresponding change in the Scaladoc section. That is
completely useless extra work. Yeah, we all have lots of extra time to
spend repeating documentation, don't we. And of course the required
changes in Scaladoc will often be forgotten or otherwise screwed up.
Yes, it could be automatically checked for consistency, but that's
just more complication and overhead, not to mention that not everyone
will bother to run the check (unless it is done automatically by the
compiler).

As I said, I am not asking that the current Scaladoc format be
eliminated. Anyone who wishes to use will be free to do so. I just
want a simpler, cleaner alternative for my own code. If the folks who
prefer the current format have to read my code, I don't see how they
could possibly be confused by the new format.

Regards,
Russ P.

http://RussP.us

On Dec 14, 3:40 am, "Peter C. Chapin" <PCh [dot] [dot] [dot] [at] vtc [dot] vsc [dot] edu> wrote:
> Having scaladoc that is extremely integrated with the code doesn't seem like
> a good thing to me. The current system keeps the documentation and code
> slightly separated which reduces clutter in the code itself while still
> allowing the documentation to be "near" the code for easier maintenance. On
> the other hand I'm the sort of person who doesn't mind maintaining
> documentation in a totally separate file (and there are reasons why that is
> sometimes better) so, for example, duplicating parameter names in the
> documentation isn't a problem for me. Anyway it seems like the scaladoc tool
> could warn about inconsistent parameter names along with similar things.

Peter,

I don't see how you can claim with a straight face that the current
Scaladoc format "reduces clutter." Maybe it's just all those
asterisks, but it looks like nothing but clutter to me! And having it
outside the documented class or function just doesn't seem quite right
to me.

I see nothing wrong with separate doc files either in some cases, but
I would use those for more detailed documentation to supplement, not
replace, what appears in Scaladoc.

I find the duplication of argument names and types in Scaladoc to be
almost offensive. It goes against the fundamental principle of
avoiding duplication of function in general to avoid divergence and
inconsistency. Think about it. Every time someone changes the
arguments of a class/method/function in any way, he needs to go up and
make the corresponding change in the Scaladoc section. That is
completely useless extra work. Yeah, we all have lots of extra time to
spend repeating documentation, don't we. And of course the required
changes in Scaladoc will often be forgotten or otherwise screwed up.
Yes, it could be automatically checked for consistency, but that's
just more complication and overhead, not to mention that not everyone
will bother to run the check (unless it is done automatically by the
compiler).

As I said, I am not asking that the current Scaladoc format be
eliminated. Anyone who wishes to use will be free to do so. I just
want a simpler, cleaner alternative for my own code. If the folks who
prefer the current format have to read my code, I don't see how they
could possibly be confused by the new format.

Yeah, I should probably take a crack at it myself one of these days.
As I have said before though, I am more of an aero engineer who
programs than a general-purpose programmer or developer. It would
probably take me ten times longer to implement than someone who has
worked on Scaladoc already. In any case, the first step is to get the
idea out there and hope it catches on.

Regards,
Russ P.

On Dec 15, 12:41 am, rkuhn wrote:

> I certainly won’t deny that you have a point (though I also do see how your
> proposed format can well look even more cluttered, depending on one’s
> style). Care to prove it with code? (hint: “I just want …” might not always
> lead to the right thing happening in an open source project)
>
> Regards,
>
> Roland
>
> PS: I am well aware that you have given to the community before, thank you
> for that! This is in no way meant to be offensive. I just want to point out
> that Scala still is and always will be an open source project.