Adopt a class! - Enhance inline documentation

Topics: Core, General
Developer
Nov 30, 2011 at 8:47 PM

The majority of the Orchard source lack inline documentation, what is especially a problem with (widely-used) API classes like the ContentManager. Documenting at least the most frequently used and referenced classes (or even more important: the interfaces they implement) would greatly shorten the learning curve one has to face when diving into module development.

What I think documentation is badly needed for:

  1. IOrchardServices interface and all of its properties' interfaces (IContentManager, ITransactionManager...) and their extensions
  2. Events exposed in handlers (all the On* methods)
  3. IDependency and its derivatives (there are already one-line summaries for all of them in the docs)
  4. ResourceRegister, ScriptRegister and maybe RequireSettings (as these are extensively used in views)

These are in my opinion the mostly used parts of Orchard that are not easy to understand (or one has to experiment).

What I'd propose is that those who develop for Orchard regularly and therefore came to understand what a class and its methods do pick a class (and/or interface) and write comments for the class itself and its methods, properties. It's not a big task if multiple volunteers do it.

I volunteer to adopt IAuthorizer, INotifier and WorkContext and if nobody wants then the three classes in point four (could also do most of IContentManager but I have some spots still white there).

Coordinator
Nov 30, 2011 at 8:49 PM

Great initiative. Thanks.

Nov 30, 2011 at 9:48 PM

I most definitely concur. I spend quite a lot of time poking around in Orchard source and working out what's going on, this would certainly occupy much less time if source documentation was stronger. Having a few more comments within method bodies couldn't hurt either, it can be really hard to follow some of the more complex functions.

So I'll start just doing this as I go along in areas I'm looking at anyway, and push up to a fork (should we establish anything specific for this, e.g. a dedicated fork or branch?)

Additionally there are areas I already know in detail that I could start covering: content management, placement, themes, shapes.

Just some general thoughts: Having documentation spread around in too many places can make things hard, especially for new users who won't know all the resources to look at. This is already becoming evident on orchardproject.net where it's easy for topics to fall behind, and there is another challenge of how do you represent documentation that has changed from one Orchard version to another. Also, each module has its own documentation in a separate place. Something we touched on in another thread was a unified help API for module developers to manage installation and usage instructions for their modules. What if we came up with a way to tie all of this together, so a module that gathers together documentation from various different sources and displays it in a browser inside Orchard. Then have a provider to scrape XML docs out of pdb files (using Sandcastle, Jolt, or similar libraries), a provider that lets you distribute Markdown docs with your modules for custom topics, and maybe some kind of webservice help server to provide e.g. user comments and amendments (and this could be part of the Gallery; ideally you could read the docs even before installing the module). It'd be quite a big project but I think make Orchard a massively end-to-end experience.

Bertrand, you previously mentioned migrating the wiki to a new system involving Hg ... I'm just wondering what is the status of that, and how it works, I'm interested if it could have any applications for a help module.

Coordinator
Nov 30, 2011 at 9:54 PM

The documentation site is actually migrated already. The new site is markdown, stored on Github. Click the edit link on any page to see it in action. I've started revising the documentation acordingly, especially the doc guidelines, but there is so much more to do... and the source code for the whole thing comes with it (wink wink nudge nudge).

About the other proposals, yes, excellent.

Developer
Nov 30, 2011 at 10:31 PM

Don't you think it would be interesting to translate the documentation for other languages?

Could the GitHub project be duplicated?

Could you provide a hosting and a subdomain (or may be just a subdirectory on the existing site)?

If so, I'd like to participate in translating the Markdown pages and making screenshots in French.

Nov 30, 2011 at 11:26 PM

That's very cool, and extremely simple code-wise. The only thing I'm wondering is how do you do the synchronisation between GitHub and your webserver, and where does MarkdownWebPages.dll come from? Couldn't find it anywhere. Very nifty anyway - not sure if/how it could fit into a module/API documentation scenario but I'd like to come up with something similar.

Coordinator
Nov 30, 2011 at 11:39 PM

The doc site is hosted on AppHarbor, and set-up to monitor the repository on Github. Every time something is checked into the main branch, the site is rebuilt automagically. It's a beautiful thing.

I'd be fine with a convention on subfolders of the main doc repo for module documentation. Module authors could work on forks of the repo, and I'd just have to take pull requests.

Antoine: feel free to fork the project for French. I can show you how to configure your own AppHarbor instance, but it should be fairly easy. And free, too.

Developer
Dec 1, 2011 at 6:36 AM

To what randompete raised: how would it be the best for new documentation to be submitted? I don't know whether multiple people can push to the same fork here, if yes, it would be OK to be the whole thing in a fork. The core team would then pull changes regularly as documentation is added (I don't think there is point in adding issues for pieces of documentation). Creating multiple forks, everybody an own one would be an option too, if it's no problem that there would be several forks for improving documentation. The branch to use is also a question, could Bertrand or Sebastien point to a direction here?

Coordinator
Dec 1, 2011 at 8:01 AM

There is only one branch so far, and I don't see a compelling reason to add others at this point.

Developer
Dec 1, 2011 at 8:48 AM

I've meant Orchard branches, just as Pete. So is it fine to add all new documentation just to the default branch in a new fork? Without opening any issues?

Developer
Dec 1, 2011 at 1:26 PM
Edited Dec 1, 2011 at 6:59 PM

I've taken a deep breath and has done some docs, in this fork I've added documentation to the following:

  • IAuthorizer: complete
  • Notifier: complete
  • WorkContext: almost complete
  • RequireSettings. ResourceRegister, ScriptRegister: partial, only the most used/confusing methods
  • IContentManager: partial; I'm not sure what groupId is in the Build* methods (is this the same group as the one specified sometimes in drivers with OnGroup()?)
  • IOrchardServices: only the New property

Where I didn't know or didn't understand fully what something was for I added of course no comment. I preserved the original style of the separation of code lines (since with comments for better overview there should be an empty line between method definitions; where there was no line before now is, where there was there are two now).

I remembered wrong as IDependency and its children are already documented.

Dec 1, 2011 at 3:28 PM
Edited Dec 1, 2011 at 3:29 PM

Maybe we could open a single workitem for all documentation. 

GroupId you can see being used on the various Settings admin pages. What happens is that an editor is rendered for the Site content item, and groupId decides which settings parts actually appear on which pages. It's an otherwise underused feature that could, for instance, be employed to create workflows or tabbed displays; something I've been meaning to get around to experimenting with! You can set a group in GetItemMetadata(...) ...

Edit: By the way, where have you seen OnGroup, or did you mean the bit I mentioned in GetItemMetadata?

Dec 1, 2011 at 3:32 PM

Bertrand: Where do you get MarkdownWebPages.dll? It's not part of MarkdownSharp, and google is drawing a blank when I look for it.

Developer
Dec 1, 2011 at 3:55 PM

Thanks Pete, that's what I've meant. Recently I've seen it in my own modules :-).

Coordinator
Dec 1, 2011 at 6:56 PM

Oh, sorry, I thought you meant branch on the doc site. Well, actually 1.x would probably have been better.

I'll ask where the markdown dll came from. I'm not sure.

Coordinator
Dec 4, 2011 at 12:35 AM

That dll was created by developers at Microsoft for this kind of purpose. There isn't that much to it, it makes it possible to route to markdown files directly.

Developer
Dec 4, 2011 at 11:25 PM
Edited Dec 4, 2011 at 11:25 PM

What can I do, then? I guess merging is not an option, or is it?

Coordinator
Dec 5, 2011 at 1:38 AM

you can easily export patches from your changes. That should be fairly easy to apply to 1.x then.

Developer
Dec 5, 2011 at 9:31 AM

I pushed the changes to the 1.x branch too. I guess the changes in default can just be ignored.

Developer
Dec 5, 2011 at 9:52 AM

I've pretty much done what I wanted to. I now see that multiple collaborators can work on the same fork, so if someone would like to add documentation, it would be best to add it to this fork. The we can submit a pull request for all the added docs.

Should I open an issue then?

Coordinator
Dec 5, 2011 at 9:14 PM

A single work item for multiple issues never works, believe me. They just stay open forever. This thread works better. I know that we said we would only take patches that are associated with an issue, but we can make an exception for this.

Developer
Dec 6, 2011 at 5:56 PM

OK. Now if anyone wants to add something to the fork, now would there be the opportunity :-).