[xwiki-devs] XWiki Velocity Documentation

List overview All Threads
Download

newer

older

[xwiki-devs] Session Variables

[xwiki-devs] [proposal] Refactor...

Ludovic Dubost

4 Aug 2008 4 Aug '08

2:12 a.m.

Hi, I've published in svn a tool based on velocidoc (http://sourceforge.net/projects/velocidoc/) to allow to generate javadoc style documentation for velocity macros. You'll find links to it and an example of generating for the XWiki Platform Web templates directory on the wiki: http://dev.xwiki.org/xwiki/bin/view/Drafts/Documenting+XWiki+Velocity+Macros From now on we should start documeting velocity macros with the following syntax: #** * Description of the macro * @param paramname desc * @param paramname desc * @author author *# A later improvement will allow parsing XWiki xml files and extract documentation of the pages in the same format. Ludovic -- Ludovic Dubost Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost

Attachments:

ludovic.vcf (text/x-vcard — 304 bytes)

Show replies by date

Thomas Mortagne

4 Aug 4 Aug

9:43 a.m.

2008/8/4 Ludovic Dubost <ludovic(a)xwiki.com>om>:

...

Great Idea ! We now have to add this to our maven build to generate it for each release.

...

Ludovic -- Ludovic Dubost Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost _______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne

vincent＠massol.net

10:26 a.m.

yes and we need to separate public velocimacros from non public ones -Vincent On 8/4/08, Ludovic Dubost <ludovic(a)xwiki.com> wrote:

...

Ludovic Dubost

11:07 a.m.

I'm not sure there is a such thing as public/non public. However we can tell which one we support in the API. Ludovic vincent(a)massol.net wrote:

...

yes and we need to separate public velocimacros from non public ones -Vincent On 8/4/08, Ludovic Dubost <ludovic(a)xwiki.com> wrote:

_______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Ludovic Dubost Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost

Pascal Voitot

2:59 p.m.

I was exactly thinking about something like that yesterday ;) great!!! Pascal On Mon, Aug 4, 2008 at 11:07 AM, Ludovic Dubost <ludovic(a)xwiki.org> wrote:

...

I'm not sure there is a such thing as public/non public. However we can tell which one we support in the API. Ludovic vincent(a)massol.net wrote:

yes and we need to separate public velocimacros from non public ones -Vincent On 8/4/08, Ludovic Dubost <ludovic(a)xwiki.com> wrote: > Hi, > > I've published in svn a tool based on velocidoc > (http://sourceforge.net/projects/velocidoc/) to allow to generate > javadoc style documentation for velocity macros. > > You'll find links to it and an example of generating for the XWiki > Platform Web templates directory on the wiki: > >

http://dev.xwiki.org/xwiki/bin/view/Drafts/Documenting+XWiki+Velocity+Macros

From now on we should start documeting velocity macros with the following syntax: #** * Description of the macro * @param paramname desc * @param paramname desc * @author author *# A later improvement will allow parsing XWiki xml files and extract documentation of the pages in the same format. Ludovic -- Ludovic Dubost Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost

_______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Ludovic Dubost Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost _______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

Jerome Velociter

3:14 p.m.

Agreed, this is very valuable tool! For the public/private visibility, we can try to find out if there is some mean to easily add a new annotation, like @public Jerome. Pascal Voitot wrote:

...

I was exactly thinking about something like that yesterday ;) great!!! Pascal On Mon, Aug 4, 2008 at 11:07 AM, Ludovic Dubost <ludovic(a)xwiki.org> wrote:

I'm not sure there is a such thing as public/non public. However we can tell which one we support in the API. Ludovic vincent(a)massol.net wrote:

http://dev.xwiki.org/xwiki/bin/view/Drafts/Documenting+XWiki+Velocity+Macros

_______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

Ludovic Dubost

3:21 p.m.

It's probably possible though it's a bit tricky when you don't know javacc et jjtree well.. I've added getting the code of the macro itself in the process of which I understood only half of what I've been doing. I've added support of getting XWiki pages (from the file system). This should allow to document macros in pages as well as the pages themselves. What would be even more valuable would be : - to be able to read a live wiki - to be able to read usages of macros to have a cross reference This is more work and I don't have enough time for this at this point. If anybody wants to play with it, go ahead. Ludovic Jerome Velociter wrote:

...

Agreed, this is very valuable tool! For the public/private visibility, we can try to find out if there is some mean to easily add a new annotation, like @public Jerome. Pascal Voitot wrote:

I was exactly thinking about something like that yesterday ;) great!!! Pascal On Mon, Aug 4, 2008 at 11:07 AM, Ludovic Dubost <ludovic(a)xwiki.org> wrote:

I'm not sure there is a such thing as public/non public. However we can tell which one we support in the API. Ludovic vincent(a)massol.net wrote:

http://dev.xwiki.org/xwiki/bin/view/Drafts/Documenting+XWiki+Velocity+Macros

> From now on we should start documeting velocity macros with the > following syntax: > > #** > * Description of the macro > * @param paramname desc > * @param paramname desc > * @author author > *# > > A later improvement will allow parsing XWiki xml files and extract > documentation of the pages in the same format. > > Ludovic > > -- > Ludovic Dubost > Blog: http://blog.ludovic.org/ > XWiki: http://www.xwiki.com > Skype: ldubost GTalk: ldubost > > > > > _______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Ludovic Dubost Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost

vincent＠massol.net

4 p.m.

On 8/4/08, Jerome Velociter <jerome(a)xwiki.com> wrote:

...

Agreed, this is very valuable tool! For the public/private visibility, we can try to find out if there is some mean to easily add a new annotation, like @public

I meant something simpler like moving non public apis in another vm file. Right now we only have one macros.vm file.

...

Jerome. Pascal Voitot wrote:

I was exactly thinking about something like that yesterday ;) great!!! Pascal On Mon, Aug 4, 2008 at 11:07 AM, Ludovic Dubost <ludovic(a)xwiki.org> wrote:

I'm not sure there is a such thing as public/non public. However we can tell which one we support in the API. Ludovic vincent(a)massol.net wrote:

http://dev.xwiki.org/xwiki/bin/view/Drafts/Documenting+XWiki+Velocity+Macros

> From now on we should start documeting velocity macros with the > following syntax: > > #** > * Description of the macro > * @param paramname desc > * @param paramname desc > * @author author > *# > > A later improvement will allow parsing XWiki xml files and extract > documentation of the pages in the same format. > > Ludovic > > -- > Ludovic Dubost > Blog: http://blog.ludovic.org/ > XWiki: http://www.xwiki.com > Skype: ldubost GTalk: ldubost > > > > _______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

Vincent Massol

5 Aug 5 Aug

10:27 p.m.

Hi, It's cool but it looks like you've copied the source of the framework. It would be much nicer if we could use the jar (haven't researched it so don't know how easy it is or not). It also needs some maven integration since I've seen a sh file and it seems the dependent jars are not downloaded automatically. Someone would need to spend 1-2 days on it to make it usable, integrated and clean before we can use it on our projects. Thanks -Vincent On Aug 4, 2008, at 2:12 AM, Ludovic Dubost wrote:

...

Hi, I've published in svn a tool based on velocidoc (http://sourceforge.net/projects/velocidoc/ ) to allow to generate javadoc style documentation for velocity macros. You'll find links to it and an example of generating for the XWiki Platform Web templates directory on the wiki: http://dev.xwiki.org/xwiki/bin/view/Drafts/Documenting+XWiki+Velocity+Macros From now on we should start documeting velocity macros with the following syntax: #** * Description of the macro * @param paramname desc * @param paramname desc * @author author *# A later improvement will allow parsing XWiki xml files and extract documentation of the pages in the same format. Ludovic

Ludovic Dubost

10:56 p.m.

I've made significant modifications to the original project, which is not very modular. The project code is more than 5y old. But I agree there is a need for maven integration and a nice cleanup. However I'm not so good to make a nice maven project than would make it easy to generate the docs from maven commands. Anybody wants to do it ? Ludovic Vincent Massol wrote:

...

Hi, I've published in svn a tool based on velocidoc (http://sourceforge.net/projects/velocidoc/ ) to allow to generate javadoc style documentation for velocity macros. You'll find links to it and an example of generating for the XWiki Platform Web templates directory on the wiki: http://dev.xwiki.org/xwiki/bin/view/Drafts/Documenting+XWiki+Velocity+Macros From now on we should start documeting velocity macros with the following syntax: #** * Description of the macro * @param paramname desc * @param paramname desc * @author author *# A later improvement will allow parsing XWiki xml files and extract documentation of the pages in the same format. Ludovic

_______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Ludovic Dubost Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost

6035

days inactive

6036

days old

xwiki-devs@xwiki.org

Manage subscription

9 comments

7 participants

tags (0)

participants (7)

Jerome Velociter
Ludovic Dubost
Ludovic Dubost
Pascal Voitot
Thomas Mortagne
Vincent Massol
vincent＠massol.net