phpautodoc-devel Mailing List for Inline PHP API Documentation

On Mit, 2003-01-15 at 23:49, Jason Hines wrote: 
> First, THANK YOU for this nice tool.  It is a very appealing alternative
> to the other system I've looked into. (phpDoc, phpDocu).

Glad you like it. BTW are you aware of http://www.phpdoc.de/ ?
Apparently, it's officially supported by the PHP developers.

> The only "issue" I have is the generated HTML.  It would be nice to be 
> able to alter the outputted HTML easily, and apply a stylesheet.  
> Unfortunately, this will not be so easy, as all the markup is hardcoded 
> into the fwrite() calls.
> 
> I'm curious if there has been any interest in adding simple template
> capabilities, so that one could edit the HTML in a uniform and elagant
> fashion.

Well, obviously you're interested in it. :)

> If there is interest, I may be able to lend a hand in adding this
> capability.  

That would be great!

> My sourceforce ID: openface

I'm sure you understand we can't just give you access before seeing some
code. Post a patch that shows how you'd like to tackle this and I'll
gladly give you access.


-- 
Earthling Michel Dänzer (MrCooper)/ Debian GNU/Linux (powerpc) developer
XFree86 and DRI project member   /  CS student, Free Software enthusiast

First, THANK YOU for this nice tool.  It is a very appealing alternative
to the other system I've looked into. (phpDoc, phpDocu).  The only
"issue" I have is the generated HTML.  It would be nice to be able to
alter the outputted HTML easily, and apply a stylesheet.  Unfortunately,
this will not be so easy, as all the markup is hardcoded into the
fwrite() calls.

I'm curious if there has been any interest in adding simple template
capabilities, so that one could edit the HTML in a uniform and elagant
fashion.

If there is interest, I may be able to lend a hand in adding this
capability.  My sourceforce ID: openface

Thanks again,
jason

Bugs item #655063, was opened at 2002-12-16 23:31
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=107183&aid=655063&group_id=7183

Category: Code
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Brian Williams (tuzen)
Assigned to: Nobody/Anonymous (nobody)
Summary: paths with backslashes cause problems

Initial Comment:
...and my OS doesn't support forward slashes.

<b>Warning</b>:  file("/..\Web\myfile.php") - No such 
file or directory in <b>.
\phpautodoc\phpdoc.php</b> on line <b>380</b><br>
<br>

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=107183&aid=655063&group_id=7183

[ CC: to the phpautodoc development list ]

On Sun, 2002-07-07 at 23:39, Stephane wrote:
>=20
> I discovered phpautodoc with your email.
> Of course, I'm interesting to exchange ideas on
> the releationship between phpdocgen and
> phpautodoc.
> But because phpdocgen is written in Perl
> and phpautodoc seems to be written in PHP,
> I think they must have separated lifes.

:)

What phpautodoc needs most badly IMO is a better parser. perl might be
better for that, but I don't know if there's a reasonable way to mix PHP
and perl. And I'd hate to reimplement all of it in perl because the code
serves as an example for the inline documentation like this.

> Perhaps we can study the support of the same
> documentation syntax for the two tools.
> Currently, the release 0.2 of phpdocgen
> proposes a good set of tags. See
> http://www.arakhne.org/tools/phpdocgen.php
> for more details.

That's indeed quite an impressive list, but it seems to me a lot of
those tags simply aren't needed with phpautodoc because it retrieves the
information automatically.


--=20
Michel D=E4nzer          |       Iogram AG       |        http://iogram.ch
Laupenstrasse 1        |       3008 Bern       |      +41 (0)1 465 45 45

CVSROOT:	/cvsroot/phpautodoc
Module name:	phpautodoc
Repository:	./
Changes by:	chris_schneider@usw-pr-cvs1.	01/11/29 01:17:22

Log message:
  Work-around for function foo(){ vs. function foo() { problem (bug #486429)

Modified files:
      ./:
        phpdoc.php 
  
  Revision      Changes    Path
  1.20          +2 -1      phpautodoc/phpdoc.php

Bugs item #486429, was opened at 2001-11-28 03:22
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=107183&aid=486429&group_id=7183

Category: Code
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Josjojo (josjojo)
Assigned to: Nobody/Anonymous (nobody)
Summary: 'function f($g){' not processed correct

Initial Comment:
When there is a '{' directly after the ')' the 
function will not be processed correctly.

Look at this example:
function f($g){
  //Do something
}

This function will not be processed correctly. To let 
phpdoc.php let it process correctly the function has 
to have a space between ')' and '{'.

The corrected function (function from above):
function f($g) {
  //Do something
}

Please correct this. Thanks.

----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=107183&aid=486429&group_id=7183

Bugs item #486428, was opened at 2001-11-28 03:15
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=107183&aid=486428&group_id=7183

Category: Code
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Josjojo (josjojo)
Assigned to: Nobody/Anonymous (nobody)
Summary: function f($g){'

Initial Comment:
PHP Sourcecode (witch is processed):


----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=107183&aid=486428&group_id=7183

CVSROOT:	/cvsroot/phpautodoc
Module name:	phpautodoc
Repository:	./
Changes by:	mdaenzer@usw-pr-cvs1.	01/10/01 03:21:35

Log message:
  merge fixes from trunk

Modified files:
      ./:	Tag: release-0_1-branch
        layout_box.class phpdoc.php 
  
  Revision      Changes    Path
  1.5.2.2       +2 -2      phpautodoc/layout_box.class
  1.18.2.2      +2 -2      phpautodoc/phpdoc.php

CVSROOT:	/cvsroot/phpautodoc
Module name:	phpautodoc
Repository:	./
Changes by:	chris_schneider@usw-pr-cvs1.	01/10/01 02:39:17

Log message:
  Fix problem with default table width being set to 100\% instead of 100%

Modified files:
      ./:
        layout_box.class 
  
  Revision      Changes    Path
  1.7           +2 -2      phpautodoc/layout_box.class

Patches item #459898, was opened at 2001-09-08 19:26
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=307183&aid=459898&group_id=7183

Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Carlos Romel (cromel)
Assigned to: Nobody/Anonymous (nobody)
Summary: Bug managing -- parameter

Initial Comment:
	PHPdoc does not identify -- parameter very 
well, managing it as normal file.

Ex.: $ grep "doc:" -A1 Makefile
doc: snapshot
    cd ..;    php $(PHPDOC) roko/*.php -- -o $(CURDIR)/doc;    cd -


----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=307183&aid=459898&group_id=7183

CVSROOT:	/cvsroot/phpautodoc
Module name:	phpautodoc
Repository:	./
Changes by:	smueller@usw-pr-cvs1.	01/05/14 05:49:06

Log message:
  mergeing changes from release-0_1-branch

Modified files:
      ./:
        layout_box.class pd_arg.class pd_class.class 
        pd_entity.class pd_function.class pd_var.class phpdoc.php 
        test.class 
  
  Revision      Changes    Path
  1.6           +23 -32    phpautodoc/layout_box.class
  1.6           +16 -11    phpautodoc/pd_arg.class
  1.16          +28 -71    phpautodoc/pd_class.class
  1.13          +21 -40    phpautodoc/pd_entity.class
  1.13          +37 -44    phpautodoc/pd_function.class
  1.6           +16 -11    phpautodoc/pd_var.class
  1.19          +162 -128  phpautodoc/phpdoc.php
  1.4           +16 -12    phpautodoc/test.class

"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

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 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

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 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

Dan Kuykendall wrote:

> Have any of you tried to get thos to work by way of the webserver and
> browser?
> Right now it seems to want the be run from the command line, but for
> those without a PHP binary (apache dso only) its a bit of a pain.


I think it should be rather easy to build a web front-end which uses the=20
existing code. Put the top-level code of the main script into a function=20
main() and call that with appropriate arguments.


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

Have any of you tried to get thos to work by way of the webserver and
browser?
Right now it seems to want the be run from the command line, but for
those without a PHP binary (apache dso only) its a bit of a pain.

Seek3r

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

CVSROOT:	/cvsroot/phpautodoc
Module name:	phpautodoc
Repository:	./
Changes by:	mdaenzer@usw-pr-cvs1.	01/04/03 12:15:47

Log message:
  Maintenance release:
  
  * fix directory crawling, try to avoid infinite loops
  * clean up HTML

Modified files:
      ./:	Tag: release-0_1-branch
        layout_box.class pd_arg.class pd_class.class 
        pd_entity.class pd_function.class pd_var.class phpdoc.php 
        test.class 
  
  Revision      Changes    Path
  1.5.2.1       +23 -32    phpautodoc/layout_box.class
  1.5.2.1       +16 -11    phpautodoc/pd_arg.class
  1.15.2.1      +28 -71    phpautodoc/pd_class.class
  1.12.2.1      +21 -40    phpautodoc/pd_entity.class
  1.12.2.1      +37 -44    phpautodoc/pd_function.class
  1.5.2.1       +16 -11    phpautodoc/pd_var.class
  1.18.2.1      +161 -127  phpautodoc/phpdoc.php
  1.3.2.1       +16 -12    phpautodoc/test.class

CVSROOT:	/cvsroot/phpautodoc
Module name:	CVSROOT
Repository:	./
Changes by:	mdaenzer@usw-pr-cvs1.	01/03/01 00:35:20

Log message:
  not needed

Modified files:
      ./:
        checkoutlist 
  
  Revision      Changes    Path
  1.3           +0 -1      CVSROOT/checkoutlist