Forty Six and Two: 2011

Some ideas for projects that would scratch a few itches I have. However it’s unlikely that I’ll ever have to time to actually get round to doing them myself, so by blogging about them I hope someone who is looking for ideas can pick one of these up and make them real. Hope there is some room after New Year’s resolutions! The difficulty and work involved varies widely. Look at it this way – if you pick one of these up, you can be assured you’ll have at least one user.

A usable documentation system

I’m not talking about xml doc comments here (although that is a part of it). It should be possible to come up with a good domain specific language to write documentation of any kind – be it straightforward API documentation, a tutorial or a cookbook, that is easy to keep up to date with the current API you’re documenting, and that can export to a variety of different formats.

My main inspiration here is Scribble, for Racket (formerly PLT Scheme). From the scribble paper’s abstract:

Scribble is a system for writing library documentation, user guides, and tutorials. It builds on PLT Scheme’s technology for language extension, and at its heart is a new approach to connecting prose references with library bindings. Besides the base system, we have built Scribble libraries for JavaDoc-style API documentation, literate programming, and conference papers. We have used Scribble to produce thousands of pages of documentation for PLT Scheme; the new documentation is more complete, more accessible, and better organized, thanks in large part to Scribble’s ﬂexibility and the ease with which we cross-reference information across levels. This paper reports on the use of Scribble and on its design as both an extension and an extensible part of PLT Scheme.

The cool thing here is that you write your documentation in Scheme itself – you write a function or member in your text, and it uses the default name resolution rules to look up what you’re referring to, and if you say export to HTML, adds a hyperlink to the actual API documentation for that particular function. Also you can write a short program, have it typeset in place, along with the results of running the program. That would be hugely useful for cookbook style documentation.

I realize it is probably not possible to do this in F# in the same way due to the lack of macros. Maybe ClojureCLR would be a better choice. On the other hand, now that the F# compiler is open source – how about a compiler extension? For some inspiration closer to home, have a look at BumbleBee. Bonus points for Visual Studio integration.

Difficulty: Medium. The hard part is figuring out how to do this cleanly – but maybe a fairly straightforward pre-processor is enough to make people happy.

Work: Lots. Getting all this stuff to work together reliably and preferably inside Visual Studio...that’ll take some time.

Mirror-based reflection library

Let’s face it. The reflection APIs in .NET suck. First of all, because I have to write APIs, and not API – I mean there’s System.Reflection, System.Reflection.Emit, CodeDOM, the Debugger API (what else is debugging if not reflecting over your code?), a separate API for F# reflection (and probably for any language that’s not C# or VB), Cecil, ReflectionOnlyLoad, Metadata reading in the F# PowerPack, and so on.

This indicates insufficient abstraction of System.Reflection: if I’m playing with F# types, I cannot use GetType() – this exposes internal implementation details! The reflection API by itself cannot cope with other languages, or other types of reflection – hence the need for e.g. a separate debugging API, as it needs to cope with distributed debugging. Or for things like Cecil, to cope with situations where you don’t want to load an assembly and all its dependencies when you’re reflecting over it. Sadly, this sometimes makes it look like I'm learning the same old reflection API over and over again, except someone’s changed all the names. And don’t get me started on how many times Type is overloaded. High cohesion, anyone?

Enter mirror-based reflection, which is an idea that might solve these problems. Except of course, .NET does not have a library that uses this type of reflection. This is where you come in...for inspiration, Newspeak has the beginnings of such an API. It should be possible to have a specific API that is clear in the limits of what it can do, while still sharing much of the concepts with very similar systems – imagine being able to use Cecil and System.Reflection but with the same names for everything possible. And if you ever need to reflect over a running program, you can use the debugging API, except you can leverage your existing knowledge. Obviously, the library should be pluggable so that people can plug their own reflection libraries in there.

Difficulty: This may be a research problem. On the other hand, there are things to build on, and a motivated person or team could build, say, an introspection only API in a reasonable amount of time.

Work: lots and lots, obviously. However, a proof of concept API that just does introspection of structure (not behaviour) would be enough to get more people on board and would already be useful.

Contribute to NuGet so it knows about F#

NuGet is a package manager for .NET . The current release does not work with F# – boo! However looks like David Fowler actually already went ahead and contributed some code to make this work! Excellent. However, keep voting the issue up so the NuGet team adds it to the next release :)

Difficulty: shouldn’t be all too hard – I gleaned at the source code and it looks like they’re using the Visual Studio Automation API. I know the F# project system’s implementation here is kind of shaky, so probably a bunch of workarounds is needed.

Work: Not too much – mostly finding your way around the NuGet codebase and finding what works and what doesn’t in the F# language service..

Add snippets and organize usings support to the F# project system

I miss snippets. Sure, everything in F# is nice and short so the official story is that this isn’t needed as much as in C#, but still...oh, and while you’re at it, and now the compiler is open source (I love saying that – it makes everything look so easy) can we have organize usings too please? Bonus points for adding Refactor –> Rename.

Difficulty: Straightforward. Only roadblock could be that the current F# language service is just not easily extensible for these kinds of things.

Work: Reasonable. Finding your way around the Visual Studio language service extensibility model, and the F# compiler. Knowledge about this seems very useful to have, but I can’t deny it would take some time, obviously.

That should give you enough to pass the time in 2011, I hope!

Share this post :