[ensembl-dev] Upgrade the mail-list

Kieron Taylor ktaylor at ebi.ac.uk
Wed May 9 16:55:23 BST 2012


On 09/05/12 09:45, Andreas Kusalananda Kähäri wrote:
> On Wed, May 09, 2012 at 09:38:09AM +0100, PATERSON Trevor wrote:
>> I agree entirely with Jay that the Doxygen documentation is extremely poorly designed and hard to read - is there any reason not to revert to the old perldoc format? OK it looks clunky compared to Doxygen - but IMHO readable content is more important than a cool style - or is that heresy to the Facebook generation?
>
> One of the greatest benefits of the new doxygen-based documentation is
> that you easily see the inherited methods in each sub-class.  This alone
> is reason to not go back to the "perldoc" thingy we had before.
>
> I don't get the reference to Facebook.  Care to elaborate?
>
> Cheers,
> A
>

Thanks Andreas. At the risk of further off-topic diversion, I can 
enumerate the other reasons for making the switch:

Pros of Doxygen based system:

Full comprehension of inheritance and inclusion for module dependencies
Search with autocomplete
Index by method name
Automatic cross-linking between classes
Scope for further improvement, developer support

Cons:
Too many views of the same information - kitchen sink approach
Perl a bad fit for pure OO modelling
"Programmer" lingo unfriendly to casual coders with no formal training

Pros of PDoc (the old system):
Bold and simple layout for individual modules

Cons:
HTML frames interfering with Ensembl web site.
Click-through inheritance
PDoc unmaintained and difficult to upgrade
"Classic HTML" look
Code for methods not next to method documentation

I tried to implement proper inheritance in PDoc and failed. It was 
demanding almost a complete rewrite, as PDoc was not intended to be 
OO-aware from the ground up. When I first looked at it, the PDoc output 
was as obtuse and difficult to read as the Doxygen output appears to you.

Doxygen is exceedingly flexible so there is scope for improving the 
presentation of the documentation. I hope I can find the time to do this.

In addition, we are finding good results in our API training courses 
where we spend a few minutes briefing the users on how to use the 
documentation. In my opinion, new users on the courses are getting into 
the coding more quickly than with the PDoc system.

It is not my call to make, but Ensembl is not likely to revert to the 
old system any time soon. The benefits outweigh the uncomfortable 
transition from one interface to another.

-- 
Kieron Taylor Ph.D.
Ensembl Core software developer

EMBL - European Bioinformatics Institute
Wellcome Trust Genome Campus
Hinxton, Cambridge CB10 1SD
United Kingdom




More information about the Dev mailing list