scaladoc and heat seeking beetles

What about changing the documentation strategy (of course with proper deprecation cycle)
@scaladoc("""Ur stuff goes here""")
def foo = 0
And make then whatever compiler plugin can do what it wants with it?

Just got bitten by some weird bugs in scaladoc that dropped sections of the doc because of something like [[pigdog]]
Cheers, √

On Mon, Feb 6, 2012 at 6:54 PM, Paul Phillips <paulp@improving.org> wrote:

[Moved to scala-internals]

I do not write appeals of this nature with any frequency, and I
don't expect to make a habit of it. I recently experienced a couple
days where I allowed myself to pay no attention to all those little
matters which arise every day, and just work on the codebase. In the
process I was reminded of how much I can accomplish under optimal
conditions, and it motivates me to make sure people understand how
much all those little things are costing us.

Also, this is not aimed at Hubert, or anyone, in particular, and the
question I'm responding to is perfectly reasonable.

On Mon, Feb 6, 2012 at 2:15 AM, Hubert Plociniczak
<hubert.plociniczak@epfl.ch> wrote:
> Isn't the reason why scaladoc is for example built in scala-checkin exactly
> to discover compiler bugs early?
> AFAIK some serious bugs forced us to do so and I feel that we will back
> again at the start of this nice circle if we remove it.

What compiler bugs has scaladoc uncovered? As far as I can remember
them, the bugs which have been discovered at the intersection of the
compiler and scaladoc have been bugs in scaladoc. One's perspective
on the responsible component may depend on the angle from which one
views things, because they are likely of the form "the compiler
does some ostensibly internal, totally undocumented thing one way,
scaladoc does it a slightly different way, the compiler assumes it
was done in the compiler's way, and now scaladoc crashes."

I say bugs of that form are scaladoc bugs. And it is a practical
necessity that they be considered scaladoc bugs because I cannot
have all my time frittered away trying to pull all the secondary
components along with the compiler and to diagnose every mystery
which arises in the face of what should be compiler-internal
modifications. (I trust nobody will dream of suggesting I owe even
more time to such endeavors.) And when things go wrong, it is almost
unheard of for them to be put right without my involvement. Either
I fix them or I diagnose them - and diagnosing is often, usually in
fact, more time-consuming than fixing.

I've spent something like four years now working on this codebase,
thousands and thousands of hours, and throughout I have poured large
amounts of time into matters which I have no direct interest in,
only because nobody was doing those things and I wasn't willing
to let them go undone. This is more true now than ever. We would
be smart to figure out a way to make this less true, because to
be honest I'm the only one close to having the whole codebase in
my head, which makes me the only one likely to undertake some
increasingly necessary tasks - at least, the only likely to do so
successfully.

In the shawshank redemption, the protagonist says it comes down to a
simple choice: get busy living, or get busy dying. That's the choice
before our codebase. If we don't get it under better control, yet
new bodies of code keep showing up, then it's going to get worse and
worse, and it's far from assured my head will be able to stay ahead
of it, let alone do anything about it.

There's probably a certain amount of stockholm syndrome going around
when it comes to scalac, that and/or the natural human tendency to
adapt one's definition of normal to one's present circumstances.
Maybe I ought to have lost my naive idealism by this point, but
I still think even at this late(r) hour that I can evolve the
compiler to a place with an order of mangnitude fewer bugs. The only
limits I acknowledge are those imposed by the universe: time is
finite. In open acknowledgement of that limitation, I plead to be
better insulated from day-to-day firefighting so we can all enjoy
the benefits of fireproof tuxedos, flame-retardant landscaping,
goggles which reveal traces of smoke to the wearer, and heat seeking
beetles[1], all of which are being developed in my lab and none
of which I can finish while dodging backdrafts in the abandoned
warehouse on route 61.

[1] http://indianapublicmedia.org/amomentofscience/fire-beetles/

--
Viktor Klang

Akka Tech LeadTypesafe - The software stack for applications that scale

Twitter: @viktorklang

2012/2/6 √iktor Ҡlang :
> What about changing the documentation strategy (of course with proper
> deprecation cycle)
>
> @scaladoc("""
> Ur stuff goes here
> """)
> def foo = 0
>
> And make then whatever compiler plugin can do what it wants with it?
>
> Just got bitten by some weird bugs in scaladoc that dropped sections of the
> doc because of something like [[pigdog]]

I wonder, instead, if Scaladoc cannot become a Presentation Compiler client.