Re: [xwiki-users] IDEA: API Documentation wiki

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

Re: [xwiki-users] IDEA: API Documentation wiki

Ludovic Dubost

Hi,

This is a brilliant idea. Indeed this would boost cooperation on the
document of the XWiki API. Also I'm a big fan of user comments like for
the MySQL documentation.
I've thought a little about it and given the amount of work we could
throw in on this and the way we currently work on the JavaDocs, I would
suggest:

1/ We import the API by reading directly the source code using velocity
scripts. We import this into XWiki Objects that comply with the each API
structure.
2/ Each function would have it's own page
3/ a form would allow to publish the official documentation of each function
4/ comments would be opened on each page
5/ Links could be automatically created to functions of the same name or
using similar Objects or types in the signature
6/ Given the amount of comments already present in the API we could
manually copy-paste the current javadoc (a more generic solution would
be to be able to import that documentation)
7/ If the work on the Wiki is conclusive and the documentation improves,
then we write a program to reimport this documentation in the source
code so that we have a javadoc compatible documentation
8/ If some people want to help we write some more program allowing to
synchronize the documentation both ways
9/ Using AJAX we could load automatically the source code of a function
from the SVN Web Viewer and show it right next to the API when needed.
We could even copy the code of the function if we which to make it
searchable.

I've written a sample script to show how easy it is to extract the list
of public APIs from the SVN Web Viewer
See http://www.xwiki.org/xwiki/bin/view/JavaDoc/WebHome

Who want's to help out writing the classes, forms and importer ?

Ludovic

THOMAS, BRIAN M (SBCSI) a écrit :

> I am quite pumped on XWiki, but the lack of documentation is driving my co-workers bats (I'm already thoroughly nuts, so it doesn't bother me, except when I've got a deadline threatened by not knowing how to do something).
>
> Ludovic and Jérémi and other tireless souls are suffering with development and support, apparently, and can't get the docs updated, even though some better documentation would at least ease the support burden.  Certainly, this mailing list is a major benefit, but searching the archives is a daunting task, since one needs not only to formulate a good query but also to search each and every one of a large number of monthly archives separately (from that perspective, probably a better indexer - one that would allow searching the entire archive at once - would be very helpful.  Or, perhaps I misunderstand and there's already a better way?  Please comment, someone, if that's the case).
>
> However, the idea that popped into my head early on this bright St. Louis Thursday morning was:  What are the possibilities of Wikifying the API Javadoc pages?  In this way, those of us who gain understanding of a particular part can share our hard-bought wisdom, lightening the load for everyone else.
>
> I have not delved into the uses of doclet technology, but it appears to me that a doclet could format its output as a wiki page could allow the wiki activity to take place as a supplement to the core  javadoc output, which remains read-only.
>
> Further, if the javadoc output provides sufficient versioning information, successive versions of a package, class, or interface could continue to use the wiki annotations until someone noted that the new version changed something that was documented.  Perhaps a scheme that recorded the version of a page that was current when the edit or comment is made would be all that was needed, so that whatever version of the javadoc was being explored, the versions of the wiki annotations valid for that version would be displayed.  Using date information might be simpler, but it would be more useful to be able to tie a document version to a javadoc file version, because annotations made when a later version was current might have been valid with earlier versions, and a simple date scheme would not allow viewers of those versions to benefit from things documented later.
>
> So an XWiki template or templates could be made that would filter the Javadoc output, modifying the external javadoc-generated links to retrieve wiki pages named for the documented entities, and displaying any annotations associated with the specific entities.  If Velocity isn't up to the job as-is, then (if I understand correctly) a plugin to its rendering engine could explore the DOM model and inject the wiki annotations appropriately.  Another way to do it would be to write Javascript so the browser could do the work, which would probably be simpler and save bandwidth on individual page sends, but lose the benefits of server caching.
>
> The above approach would probably be instead of a doclet, which I think would take the opposite approach and drive the wiki formatting from the javadoc content.  This would have the advantage of not needing any plugins or special wiki pages (maybe) and would probably be easier to accomplish but might tend to wrest control of navigation from XWiki in inconvenient ways.
>
> At any rate, the idea of making the wiki annotations independent of the javadoc pages is a major design goal and could permit anyone anywhere to put up a wiki that allowed annotating any javadoc repository, regardless of whether they controlled its content.
>
> I've discussed this far too much for one mail message, especially for one who little understands what he's talking about.  If there is interest, should we put up a page on xwiki.org to develop the requirements and design?  Or has someone already thought of this and it's already available?
>
> brain[sic]
>
> -----Original Message-----
> From: Erwan Arzur [mailto:[hidden email]]
> Sent: Thursday, March 16, 2006 3:27 AM
> To: [hidden email]
> Subject: Re: [xwiki-users] Hs_err_pid XWiki 0.9.840 + tomcat 5.5.9 + vm1.5.0_06
>
>
> Hey Leonard,
>
> yes i'm taking care of xwiki.com. Yes recently it has been a real PITA, most of the instability problem were due to comment spammers hitting us hard. Since last saturday we are running mod_security on our frontend servers and i do not have to check every hour if one of those assholes took us down again ! what a relief !
>
> (take care with the latest gotroot rules for mod_security, our apache ate all available memory then had to be killed - blacklist.conf is too big, i don't use it anymore)
>
> I'll check the system requirement route, but we don't experience VM crashes very often.
>
> One hint about your particular VM crash. As every thread appears to be locked when it happens, it seems to be garbage collecting related, and i'd investigate tuning the new generation and related stuff. I've got this already on my TODO list and will let you know the outcome.
>
> I posted a note about this on my weblog
> (http://www.arzur.net/index.php?English) where i suggest every spammers taken to courts should pay a check to the OSS anti-spam project of his choice. Another way of financing OSS. Most of the good tools in this field are open source anyway. SpamAssassin, SpamBayes, mod_security, gotroot.com ... come to mind.
>
> Erwan
>
> On 3/15/06, Leonard Lin <[hidden email]> wrote:
>  
>> Hi Yoav
>>
>> Thanks a lot for your hint.
>> As far as i have seen the problems stated on the sun-website are
>> concerning Old kernels or older glibc
>>
>> We use
>> Kernel: 2.6.9-11.ELsmp
>> glibc: 2.3.4
>>
>> Though the following link seems to me heading into a similiar
>> direction:
>> http://forum.java.sun.com/thread.jspa?threadID=643360&start=0&tstart=0
>>
>> regards
>>
>> -----Original Message-----
>> From: Yoav Shapira [mailto:[hidden email]]
>> Sent: Mittwoch, 15. März 2006 14:47
>> To: [hidden email]
>> Subject: Re: [xwiki-users] Hs_err_pid XWiki 0.9.840 + tomcat 5.5.9 +
>> vm1.5.0_06
>>
>> Hola,
>> As someone with Tomcat (though not XWiki) experience, 99% of the time
>> these SIGSEGV faults result from a problem with the JVM installation
>> missing required OS patches.  Start at
>> http://java.sun.com/j2se/1.5.0/install.html, pick the edition you're
>> installing, and click on the Linux Notes link from the resulting page
>> for required patch levels for things like glibc.  I hope that helps,
>>
>> Yoav
>>
>> On 3/15/06, jeremi joslin <[hidden email]> wrote:
>>    
>>> On 3/15/06, Leonard Lin <[hidden email]> wrote:
>>>      
>>>> Hi
>>>>
>>>> Are you running xwiki.com on a virtualized system such as VMWare?
>>>> One of our programmers suggested, that it might have something to
>>>> do with VMWare (in our case) because of the SIGSEGV issued,
>>>> Pointing to either errornous implementation in javaVM or failing
>>>> Hardware.
>>>>        
>>> No, xwiki.com is running on 3 real computers under Debian Sarge. For
>>> the rest, i don't know.
>>>
>>> Jeremi
>>> --
>>> Blog: http://www.jeremi.info
>>> LinkedIn: https://www.linkedin.com/profile?viewProfile=&key=1437724
>>> Project Manager XWiki: http://www.xwiki.org
>>> skype: jeremi23 -- msn et gtalk : [hidden email]
>>>
>>>
>>> --
>>> You receive this message as a subscriber of the
>>> [hidden email] mailing list. To unsubscribe:
>>> mailto:[hidden email]
>>> For general help: mailto:[hidden email]?subject=help
>>> ObjectWeb mailing lists service home page:
>>> http://www.objectweb.org/wws
>>>
>>>
>>>
>>>      
>> --
>> Yoav Shapira
>> Nimalex LLC
>> 1 Mifflin Place, Suite 310
>> Cambridge, MA, USA
>> [hidden email] / www.yoavshapira.com
>>
>>
>>
>>
>>
>> --
>> You receive this message as a subscriber of the
>> [hidden email] mailing list. To unsubscribe:
>> mailto:[hidden email]
>> For general help: mailto:[hidden email]?subject=help
>> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
>>
>>
>>
>>    
>
>
>  
> ------------------------------------------------------------------------
>
>
> --
> You receive this message as a subscriber of the [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?subject=help
> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
>  

--
Ludovic Dubost
XPertNet: http://www.xpertnet.fr/
Blog: http://www.ludovic.org/blog/
XWiki: http://www.xwiki.com
Skype: ldubost AIM: nvludo Yahoo: ludovic




--
You receive this message as a subscriber of the [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws