Thread: Tags you plan to support/how to add more

So far you guys support @see @param and @return which is a great start.
Whats your stratagy for adding more, or are you not planning to at all?

I am the project leader of the phpGroupWare project and I have been
spending the last week with PHPDoc which is a serious *mess* to end all
messes. The code is all but impossible to follow, and adding support for
additional tags has been a nightmare.

I was just referred to your code by one of our users and I am pleased at
how clean the code is and how few files are involved (PHPDoc has what
seems to be at least a 100 files).

Anyways, I would like a few more tags and am starting to run thru the
code and will try and add support for them myself. Here is the ones Im
looking to add

The stuff in the [] 's are just a sample of what the tag would be used
for

@author [Dan Kuykendall <da...@ku...>]
@copyright [GPL/LGPL/BSD]
@package  [appname]
@access	[public or private]
@syntax [CreateObject('app.class', 'constructor_params'); ]
@example [$phpgw->acl = CreateObject('phpgwapi.acl');]


It might also be useful to have a way to 'make up' tags. This may be a
way to support whatever tags developers want to use, but without having
to build too much extra code into your prog.
Something along the lines of:

@generic copyright [GPL/LGPL/BSD]
@generic package  [appname]
@generic access	[public or private]
@generic syntax [CreateObject('app.class', 'constructor_params'); ]
@generic example [$phpgw->acl = CreateObject('phpgwapi.acl');]

Make sense?

I am going to try and implement one or the other today as I hammer on
your code for use in our project. If I get anything working I will send
it back to you.

Seek3r

Dan Kuykendall wrote:

> So far you guys support @see @param and @return which is a great start.
> Whats your stratagy for adding more, or are you not planning to at all?
>=20
> I am the project leader of the phpGroupWare project and I have been
> spending the last week with PHPDoc which is a serious *mess* to end all
> messes. The code is all but impossible to follow, and adding support fo=
r
> additional tags has been a nightmare.
>=20
> I was just referred to your code by one of our users and I am pleased a=
t
> how clean the code is and how few files are involved (PHPDoc has what
> seems to be at least a 100 files).
>=20
> Anyways, I would like a few more tags and am starting to run thru the
> code and will try and add support for them myself.

Look for '@' in the parselines() function and follow the flow. :)


I think the parser is the part of the code which needs the most work. It =
has a=20
few bugs which are hard if not impossible to fix with the current approac=
h.


> Here is the ones Im looking to add
>=20
> The stuff in the [] 's are just a sample of what the tag would be used
> for
>=20
> @author [Dan Kuykendall <da...@ku...>]
> @copyright [GPL/LGPL/BSD]
> @package  [appname]
> @access	[public or private]
> @syntax [CreateObject('app.class', 'constructor_params'); ]
> @example [$phpgw->acl =3D CreateObject('phpgwapi.acl');]
>=20
>=20
> It might also be useful to have a way to 'make up' tags. This may be a
> way to support whatever tags developers want to use, but without having
> to build too much extra code into your prog.
> Something along the lines of:
>=20
> @generic copyright [GPL/LGPL/BSD]
> @generic package  [appname]
> @generic access	[public or private]
> @generic syntax [CreateObject('app.class', 'constructor_params'); ]
> @generic example [$phpgw->acl =3D CreateObject('phpgwapi.acl');]

Sounds like a great idea for those that don't require any special treatme=
nt,=20
others should be tags of their own IMHO.

This reminds me of HTML meta tags so what does everyone think about @meta=
? (or=20
@info? ...)


> I am going to try and implement one or the other today as I hammer on
> your code for use in our project. If I get anything working I will send
> it back to you.

Great! We're excited to hear that our code is useful and there is interes=
t in=20
further development.


PS: If I'm not mistaken, our company is looking into using phpGroupWare...

--=20
Michel D=E4nzer           |      Relog-Reagency AG      |        http://r=
elog.ch
Weinbergstrasse 108     |         8006 Z=FCrich         |     +41 (0)1 36=
8 55 55

Michel Dänzer wrote:
> 
> Look for '@' in the parselines() function and follow the flow. :)

Yeah, thats what I have been working on.

> I think the parser is the part of the code which needs the most work. It has a
> few bugs which are hard if not impossible to fix with the current approach.

I still havent really been able to get it to run for me from a browser
(my only option at this point. But since the code is so small its not
that hard to learn.

> > @generic copyright [GPL/LGPL/BSD]
> > @generic package  [appname]
> > @generic access       [public or private]
> > @generic syntax [CreateObject('app.class', 'constructor_params'); ]
> > @generic example [$phpgw->acl = CreateObject('phpgwapi.acl');]
> 
> Sounds like a great idea for those that don't require any special treatment,
> others should be tags of their own IMHO.

Thats the thinking

> This reminds me of HTML meta tags so what does everyone think about @meta? (or
> @info? ...)

Would this be used in the actual HTML header?

> Great! We're excited to hear that our code is useful and there is interest in
> further development.

Has the project been dead? I notice cvs activity stopped about 10 months
ago

> PS: If I'm not mistaken, our company is looking into using phpGroupWare...

Very cool. Let me know if you need anything.

"Dan Kuykendall (Seek3r)" wrote:

> > I think the parser is the part of the code which needs the most work. It has a
> > few bugs which are hard if not impossible to fix with the current approach.
> 
> I still havent really been able to get it to run for me from a browser
> (my only option at this point. But since the code is so small its not
> that hard to learn.

Is there really no way you can install a PHP binary?


> > > @generic copyright [GPL/LGPL/BSD]
> > > @generic package  [appname]
> > > @generic access       [public or private]
> > > @generic syntax [CreateObject('app.class', 'constructor_params'); ]
> > > @generic example [$phpgw->acl = CreateObject('phpgwapi.acl');]
> >
> > Sounds like a great idea for those that don't require any special treatment,
> > others should be tags of their own IMHO.
> 
> Thats the thinking

Alright, which is which? Here's a proposal:

var: new tag

copyright: meta

package: could be handled via directories?

access: meta (Only document public vars?)

syntax: Necessary? (anything missing from the function summaries?)

example: new tag, needs pretty-printing

What else?


> > This reminds me of HTML meta tags so what does everyone think about @meta? (or
> > @info? ...)
> 
> Would this be used in the actual HTML header?

Hadn't thought of that... If it's useful, why not?


> > Great! We're excited to hear that our code is useful and there is interest in
> > further development.
> 
> Has the project been dead?

Let's say seriously ill. ;) We haven't had as much time to work on it as we
wished...

> I notice cvs activity stopped about 10 months ago

Yep, until the 0.1.1 release recently. BTW the changes on the 0.1 branch
haven't been merged into the trunk yet.


> > PS: If I'm not mistaken, our company is looking into using phpGroupWare...
> 
> Very cool. Let me know if you need anything.

I'll tell the people working on it, thanks.


-- 
Michel Dänzer           |      Relog-Reagency AG      |        http://relog.ch 
Weinbergstrasse 108     |         8006 Zürich         |     +41 (0)1 368 55 55

I still cant get this darn code to work. I installed php on windows (for
the binary) and it wont work.

In the mean time I have started my own mini parser using your tag
format.

Seek3r

Michel Dänzer wrote:
> 
> "Dan Kuykendall (Seek3r)" wrote:
> 
> > > I think the parser is the part of the code which needs the most work. It has a
> > > few bugs which are hard if not impossible to fix with the current approach.
> >
> > I still havent really been able to get it to run for me from a browser
> > (my only option at this point. But since the code is so small its not
> > that hard to learn.
> 
> Is there really no way you can install a PHP binary?
> 
> > > > @generic copyright [GPL/LGPL/BSD]
> > > > @generic package  [appname]
> > > > @generic access       [public or private]
> > > > @generic syntax [CreateObject('app.class', 'constructor_params'); ]
> > > > @generic example [$phpgw->acl = CreateObject('phpgwapi.acl');]
> > >
> > > Sounds like a great idea for those that don't require any special treatment,
> > > others should be tags of their own IMHO.
> >
> > Thats the thinking
> 
> Alright, which is which? Here's a proposal:
> 
> var: new tag
> 
> copyright: meta
> 
> package: could be handled via directories?
> 
> access: meta (Only document public vars?)
> 
> syntax: Necessary? (anything missing from the function summaries?)
> 
> example: new tag, needs pretty-printing
> 
> What else?
> 
> > > This reminds me of HTML meta tags so what does everyone think about @meta? (or
> > > @info? ...)
> >
> > Would this be used in the actual HTML header?
> 
> Hadn't thought of that... If it's useful, why not?
> 
> > > Great! We're excited to hear that our code is useful and there is interest in
> > > further development.
> >
> > Has the project been dead?
> 
> Let's say seriously ill. ;) We haven't had as much time to work on it as we
> wished...
> 
> > I notice cvs activity stopped about 10 months ago
> 
> Yep, until the 0.1.1 release recently. BTW the changes on the 0.1 branch
> haven't been merged into the trunk yet.
> 
> > > PS: If I'm not mistaken, our company is looking into using phpGroupWare...
> >
> > Very cool. Let me know if you need anything.
> 
> I'll tell the people working on it, thanks.
> 
> --
> Michel Dänzer           |      Relog-Reagency AG      |        http://relog.ch
> Weinbergstrasse 108     |         8006 Zürich         |     +41 (0)1 368 55 55
> 
> _______________________________________________
> PHP...@li...
> http://lists.sourceforge.net/lists/listinfo/phpautodoc-devel

"Dan Kuykendall (Seek3r)" wrote:
> 
> I still cant get this darn code to work. I installed php on windows (for
> the binary) and it wont work.

That's too bad. What happens?

Might be some *nixisms int the code...


> In the mean time I have started my own mini parser using your tag
> format.

As I already said, a new parser might be good for our project. ;)


-- 
Michel Dänzer           |      Relog-Reagency AG      |        http://relog.ch 
Weinbergstrasse 108     |         8006 Zürich         |     +41 (0)1 368 55 55