[enh] Issue 2630 - Support documenting unittest code as code samples. #1342

Merged
merged 1 commit into from Feb 7, 2013

Conversation

Projects
None yet
8 participants
@ghost

ghost commented Dec 1, 2012

http://d.puremagic.com/issues/show_bug.cgi?id=2630

This enables automatically creating code samples in ddoc for unittests which are public, documented, and have a non-empty function body.

@andralex: Notice since this was your feature request.

ghost closed this Dec 8, 2012

ghost reopened this Dec 8, 2012

Member

DmitryOlshansky commented Dec 21, 2012

Would be awesome to have this as testing examples spreads awful duplication all over the place.

Unknown referenced this pull request in dlang/phobos Dec 27, 2012

Merged

Fix for issue# 9214. #1038

9rnsr was assigned Dec 27, 2012

Owner

andralex commented Dec 27, 2012

This will mark a great process improvement. @9rnsr could you please give it a look?

eskimor commented Jan 22, 2013

LGTM (although I don't know the code base or anything). Just nit picking. Why is pre static and not a simple const local variable?

And what happens if I write my unittest before the to be documented item? Would it be associated with the right thing?

@ghost

ghost commented Jan 22, 2013

Why is pre static and not a simple const local variable?

It was static in another function where it was taken from.

And what happens if I write my unittest before the to be documented item? Would it be associated with the right thing?

It must come after the declaration.

Member

yebblies commented Jan 22, 2013

With a declaration wrapped in an attribute declaration, does this correctly attach the the real declaration? Does it get displayed either way?
Would it be possible/desirable to explicitly link the unittests to the declaration they're testing?

Member

yebblies commented Jan 22, 2013

Also, does this work for unittests nested inside structs/classes/etc?

@ghost

ghost commented Jan 23, 2013

With a declaration wrapped in an attribute declaration, does this correctly attach the the real declaration?

Could you provide a problematic example?

Also, does this work for unittests nested inside structs/classes/etc?

Untested, will test and work on it soon.

Would it be possible/desirable to explicitly link the unittests to the declaration they're testing?

Hmm.. Maybe UDAs can come in handy for this?

Member

yebblies commented Jan 23, 2013

I was thinking of

pure {
   const {
      immutable {
         class A {}
       }
   }
}
///
unittest { assert(0, "Testing A?"); }

Hmm.. Maybe UDAs can come in handy for this?

That sounds interesting.

@ghost

ghost commented Jan 23, 2013

That sounds interesting.

Yeah I was thinking of:

///
class Unrelated1 { }

/// documented Foo sample code
@Foo unittest
{
}

/// 
class Unrelated2 { }

/// 
class Foo { }

This would also enable you to move all code-sample unittests wherever you want (for example at the top of the module) if you ever wanted that.

Owner

andralex commented Jan 23, 2013

Just reiterating that I'm highly interested in having this merged, so the effort of implementing it up to snuff is very welcome!

eskimor commented Jan 23, 2013

I don't know, but:
pure {
const {
immutable {
class A {}
}
}
}
seems a bit artificial. If you enclose it in braces, you usually have more than one declaration inside? And then it is unclear anyway which declaration you want to have documented. If it does not work for:

const immutable pure nothrow class A {}

this of course would be a problem. That the unittest has to be after the declaration does not seem to be a problem either, but of course behaviour has to be documented.
Using UDAs seems a good idea at first, but at second thought, what about overloaded methods? You can't reference a single one by its name then.

My personal favourite also having the advantage of backwards compatibility, would be that you reference the unittest from the documentation:
/**
* Takes a bar.

* Examples:
*   unittest@foo1
*   unittest@foo2
*/
void foo(int bar);
@foo1 unittest {
    // bli bla blue
    foo(88);
}
@foo2 unittest {
    int a=27;
    foo(27;
}

This way, it is very clear which unittest are gonna be where in the documentation. Backwards compatibility is maintained, (unittests not referenced would not be included) and unittests could be anywhere in the file. Of course implementation wise, I guess it would be more work than the current approach. But it would be very clean and flexible. (I could have multiple example sections for example. beginner, intermediate, professional, ...)

Owner

andralex commented Jan 23, 2013

The less syntax we invent the better. If in a pinch we can add the feature and leave the corner cases to enhancement requests.

ghost closed this Jan 23, 2013

Contributor

jpf91 commented Jan 23, 2013

@foo2 unittest
{
}

doesn't sound bad, but it should probably look more like a normal UDA:

@document(foo2) unittest
{
}

@document unittest //instead of marking it with ddoc comments?
{
}

also the definition of the UDA should not be put into object.di as it should not pollute the global namespace. It could be added to another module (core.test) and a public import could be added to object.di instead.

Or a solution without UDA:

///
unittest {} (attach to previous declaration)

///foo2
unittest {} (attach to foo2)

Where all of these proposals get ugly though is if foo2 is a function with overloads.

ghost reopened this Jan 23, 2013

@ghost

ghost commented Jan 23, 2013

Implemented support for cases where attributes are involved.

@ghost

ghost commented Jan 24, 2013

Also, does this work for unittests nested inside structs/classes/etc?

If you mean:

/// Outer
class Outer
{
    /// Inner
    static class Inner
    {
    }

    ///
    unittest
    {
        Inner inner = new Inner;
    }
}

///
unittest
{
    Outer outer = new Outer;
}

Then yes. If you mean:

/// Outer
class Outer
{
    ///
    unittest
    {
        Outer outer = new Outer;
    }
}

Then no. The problem is, if you later add a documented symbol above the unittest (IOW a field in the class), the unittest will be part of that symbol rather than the class. So it could easily trick people if we allowed it.

Member

yebblies commented Jan 24, 2013

Another approach could be to introduce named unittests, and let the documentation explicitly reference the relevant unittests by name. The avoids the overloads issue.
eg

/// Document foo
/// unittest: foo_example
void foo(int a, int b) { ... }

unittest("foo_example")
{
   ...
}

Unknown referenced this pull request in dlang/phobos Feb 7, 2013

Merged

Fix broken example in std.stdio; #1121

@WalterBright WalterBright added a commit that referenced this pull request Feb 7, 2013

@WalterBright WalterBright Merge pull request #1342 from AndrejMitrovic/Fix2630
[enh] Issue 2630 - Support documenting unittest code as code samples.
b941299

@WalterBright WalterBright merged commit b941299 into dlang:master Feb 7, 2013

1 check was pending

default Pass: 5, Pending: 5
Details
@ghost

ghost commented Feb 7, 2013

Edit: Nevermind it won't break anything, it's just the test-case had a leftover comment. I'll do a fixup so this is all properly tested.

@ghost

ghost commented Feb 7, 2013

Now that this is pulled we should go ahead and try to convert Phobos snippets into unittests. This should also expose any potential problems with the implementation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment