| Major trouble with PhpDocumentor [message #182308] |
Sun, 28 July 2013 01:25  |
Fiver
Messages: 35
Registered: July 2013
Karma: 0
|
Member |
|
|
Hi.
I've used PHPDoc and PhpDocumentor 1 in the past; it's always been a
pain in the neck to avoid the bugs in the software, but in the end they
did what I needed. Now I'm trying to run PhpDocumentor 2
(<http://phpdoc.org>), and after almost a full day of failed attempts,
I'm getting nowhere.
I really hope somebody familiar with this tool will read this, because I
can't find a dedicated forum or mailing list.
My current project uses features from PHP 5.4, including traits, the new
[array] syntax, and the const keyword (5.3). I've looked around, and
there aren't many docu processors that can handle these, so I'm more or
less depending on PhpDocumentor 2 to come through. Unfortunately, it
appears that this project hasn't quite recovered from the major rewrite
between v1 and v2 yet.
First, I tried to install it using the "recommended" method (via PEAR).
The following was run on an up-to-date Kubuntu Raring (13.04) box.
tl;dr: I installed phpDocumentor-beta and all available templates
------------------------------------------------------------------
root@example:~ # pear channel-discover pear.phpdoc.org
Adding Channel "pear.phpdoc.org" succeeded
Discovery of channel "pear.phpdoc.org" succeeded
root@example:~ # pear remote-list -c phpdoc
Channel phpdoc Available packages:
==================================
Package Version
phpDocumentor -n/a-
phpDocumentor_Template_abstract 1.0.3
phpDocumentor_Template_checkstyle 1.0.0
phpDocumentor_Template_new_black 1.0.4
phpDocumentor_Template_old_ocean 1.0.2
phpDocumentor_Template_responsive 1.0.1
phpDocumentor_Template_zend 1.0.2
root@example:~ # pear install phpdoc/phpDocumentor
Failed to download phpdoc/phpDocumentor within preferred state "stable",
latest release is version 2.0.0b7, stability "beta", use
"channel://pear.phpdoc.org/phpDocumentor-2.0.0b7" to install
install failed
root@example:~ # pear install phpdoc/phpDocumentor-beta
downloading phpDocumentor-2.0.0b7.tgz ...
Starting to download phpDocumentor-2.0.0b7.tgz (2,132,561 bytes)
...... (snip dots) ................done: 2,132,561 bytes
install ok: channel://pear.phpdoc.org/phpDocumentor-2.0.0b7
root@example:~ # pear install phpdoc/phpDocumentor_Template_abstract \
> phpdoc/phpDocumentor_Template_checkstyle \
> phpdoc/phpDocumentor_Template_new_black \
> phpdoc/phpDocumentor_Template_old_ocean \
> phpdoc/phpDocumentor_Template_responsive \
> phpdoc/phpDocumentor_Template_zend
downloading phpDocumentor_Template_abstract-1.0.3.tgz ...
[ snip: all templates installed fine ]
------------------------------------------------------------------
So far, so good; I can now run `phpdoc template:list` and get the
following output:
Available templates:
* checkstyle
* abstract
* zend
* new_black
* responsive-twig
* responsive
* xml
* old-ocean
* new-black
* old_ocean
As it turns out, only two of these 10 (8 without dupes) are even
remotely usable.
The following error out:
* abstract; responsive; zend:
Error: Structure.xml file was not found in the target directory, is
the XML writer missing from the template definition?
* new_black; old_ocean:
Error: Writer "Search" does not exist
These run, but will do nothing useful (without a major effort):
* checkstyle; xml:
Output is a single XML file without stylesheet.
* new-black:
No errors, but also no visible data.
The two that "worked":
* old-ocean:
Works, but will need serious adjustments to be readable (all classes
are duplicated; no links to source code; many tag values missing,
like @author or @version)
* responsive-twig:
The default template. Left navigation is missing; links are broken;
layout is broken; the toggle buttons only show up 10% of the time; no
links to source code.
Very disappointing.
Next, I tried the alternate install method (the .phar file). This seems
to work better, because it apparently contains more recent versions of
the templates. I don't get errors anymore, but the output is still very
unsatisfactory (same bugs as above).
I could bite the bullet and build my own template. For that I should
copy and adjust an existing current (and working) template. But I have
no idea where to find them! They're not included in the PhpDocumentor
repository, and <http://phpdoc.org/templates> only gives me screenshots
and names, but no code. Anyway, before I start that, I'd like to ask you:
Did any of you get this to work?
I know... it's beta software, but since v1 is now unmaintained and won't
be able to handle PHP 5.4, that's all there is.
I also looked at some alternate solutions:
- Doxygen: doesn't know about PHP's traits, namespaces, etc
- Sami: has a *million* dependencies, including Symfony, Composer,
Twig, and many others. This will be hard to deploy.
(but it's pretty)
- Doc-O-Matic, TwinText: Windows only
- phpSimpleDoc: 1 developer, no community, last release 2009
- Apple's HeaderDoc: not suited for PHP 5.4 at all
- ROBODoc: unique incompatible docu syntax, no PHP 5.4
I'm lost and open for any advice.
Thanks in advance,
5er
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182309 is a reply to message #182308] |
Sun, 28 July 2013 01:38  |
Jerry Stuckle
Messages: 2598
Registered: September 2010
Karma: 0
|
Senior Member |
|
|
On 7/27/2013 9:25 PM, Fiver wrote:
> Hi.
>
> I've used PHPDoc and PhpDocumentor 1 in the past; it's always been a
> pain in the neck to avoid the bugs in the software, but in the end they
> did what I needed. Now I'm trying to run PhpDocumentor 2
> (<http://phpdoc.org>), and after almost a full day of failed attempts,
> I'm getting nowhere.
> I really hope somebody familiar with this tool will read this, because I
> can't find a dedicated forum or mailing list.
>
<snip>
>
> I'm lost and open for any advice.
>
>
> Thanks in advance,
> 5er
>
What about the links on the phpdoc.org site ("Contact us", "Report a
bug", etc.)?
When dealing with a product, the first place to go should be that
product's support structure. No one will know the product as well as
those who wrote it.
--
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex(at)attglobal(dot)net
==================
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182312 is a reply to message #182309] |
Sun, 28 July 2013 02:14 |
Fiver
Messages: 35
Registered: July 2013
Karma: 0
|
Member |
|
|
On 2013-07-28 03:38, Jerry Stuckle wrote:
> What about the links on the phpdoc.org site ("Contact us", "Report a
> bug", etc.)?
>
> When dealing with a product, the first place to go should be that
> product's support structure. No one will know the product as well as
> those who wrote it.
Their support structure, as far as I can tell, is GitHub. I could file a
new issue for every problem I encountered, sure, but that would a) swamp
their bugtracker, and b) be premature until I can eliminate the
possibility that I'm simply doing something wrong. I saw *so* many bugs
that I need to rule out a systematic error on my part first. If they had
a forum or mailing list, I would certainly try that first.
I would also like to know what everybody else is doing to document their
source code when they're using PHP 5.4 syntax. I find it hard to believe
that I'm alone in this situation.
Thanks,
5er
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182313 is a reply to message #182312] |
Sun, 28 July 2013 02:22 |
Jerry Stuckle
Messages: 2598
Registered: September 2010
Karma: 0
|
Senior Member |
|
|
On 7/27/2013 10:14 PM, Fiver wrote:
> On 2013-07-28 03:38, Jerry Stuckle wrote:
>> What about the links on the phpdoc.org site ("Contact us", "Report a
>> bug", etc.)?
>>
>> When dealing with a product, the first place to go should be that
>> product's support structure. No one will know the product as well as
>> those who wrote it.
>
> Their support structure, as far as I can tell, is GitHub. I could file a
> new issue for every problem I encountered, sure, but that would a) swamp
> their bugtracker, and b) be premature until I can eliminate the
> possibility that I'm simply doing something wrong. I saw *so* many bugs
> that I need to rule out a systematic error on my part first. If they had
> a forum or mailing list, I would certainly try that first.
>
> I would also like to know what everybody else is doing to document their
> source code when they're using PHP 5.4 syntax. I find it hard to believe
> that I'm alone in this situation.
>
> Thanks,
> 5er
>
This still isn't a good place to ask such questions. I suspect very
few, if anyone, uses it. They also have a "Contact us" link you can
use. You might make a suggestion they add a forum. Or, if you can't
figure out if you're doing something wrong, start filing bug reports.
If the documentation is that unclear, maybe it needs to be fixed.
Personally, much of my code is documented before any code is written
(it's called a "design"). It may or may not be a complete design,
depending on the complexity of the project. But the rough outlines are
there. Then I add any additional details as I go along.
--
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex(at)attglobal(dot)net
==================
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182314 is a reply to message #182313] |
Sun, 28 July 2013 02:45 |
Fiver
Messages: 35
Registered: July 2013
Karma: 0
|
Member |
|
|
On 2013-07-28 04:22, Jerry Stuckle wrote:
> On 7/27/2013 10:14 PM, Fiver wrote:
>> Their support structure, as far as I can tell, is GitHub. I could file a
>> new issue for every problem I encountered, sure, but that would a) swamp
>> their bugtracker, and b) be premature until I can eliminate the
>> possibility that I'm simply doing something wrong. I saw *so* many bugs
>> that I need to rule out a systematic error on my part first. If they had
>> a forum or mailing list, I would certainly try that first.
>>
>> I would also like to know what everybody else is doing to document their
>> source code when they're using PHP 5.4 syntax. I find it hard to believe
>> that I'm alone in this situation.
> This still isn't a good place to ask such questions. I suspect very
> few, if anyone, uses it.
This may not be the ideal place to ask, but as I said, I haven't found
anything directly relevant. There's a good chance that others in this
group are using, or have used, PhpDocumentor; it used to be the number
one documentation generator for PHP. I'll stick around for a couple of
days and see if somebody who has worked with it has a suggestion.
> They also have a "Contact us" link you can
> use. You might make a suggestion they add a forum. Or, if you can't
> figure out if you're doing something wrong, start filing bug reports.
> If the documentation is that unclear, maybe it needs to be fixed.
I maintain and contribute to several FOSS projects, and I know from
experience that support requests in a bug tracker are rarely
appreciated. But yeah, unless I can find out what I'm doing wrong,
that's what I'll have to do.
> Personally, much of my code is documented before any code is written
> (it's called a "design"). It may or may not be a complete design,
> depending on the complexity of the project. But the rough outlines are
> there. Then I add any additional details as I go along.
Okay, but what do you use to process your inline documentation?
Design, documentation and tests first is a nice principle, but I've
never seen a (non-trivial) project go from design to production without
significant changes. Having to maintain separate documentation files in
parallel to the source is asking for trouble, IMHO. But to each their own.
Thanks,
5er
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182315 is a reply to message #182314] |
Sun, 28 July 2013 02:59 |
Jerry Stuckle
Messages: 2598
Registered: September 2010
Karma: 0
|
Senior Member |
|
|
On 7/27/2013 10:45 PM, Fiver wrote:
> On 2013-07-28 04:22, Jerry Stuckle wrote:
>> On 7/27/2013 10:14 PM, Fiver wrote:
>>> Their support structure, as far as I can tell, is GitHub. I could file a
>>> new issue for every problem I encountered, sure, but that would a) swamp
>>> their bugtracker, and b) be premature until I can eliminate the
>>> possibility that I'm simply doing something wrong. I saw *so* many bugs
>>> that I need to rule out a systematic error on my part first. If they had
>>> a forum or mailing list, I would certainly try that first.
>>>
>>> I would also like to know what everybody else is doing to document their
>>> source code when they're using PHP 5.4 syntax. I find it hard to believe
>>> that I'm alone in this situation.
>
>> This still isn't a good place to ask such questions. I suspect very
>> few, if anyone, uses it.
>
> This may not be the ideal place to ask, but as I said, I haven't found
> anything directly relevant. There's a good chance that others in this
> group are using, or have used, PhpDocumentor; it used to be the number
> one documentation generator for PHP. I'll stick around for a couple of
> days and see if somebody who has worked with it has a suggestion.
>
>> They also have a "Contact us" link you can
>> use. You might make a suggestion they add a forum. Or, if you can't
>> figure out if you're doing something wrong, start filing bug reports.
>> If the documentation is that unclear, maybe it needs to be fixed.
>
> I maintain and contribute to several FOSS projects, and I know from
> experience that support requests in a bug tracker are rarely
> appreciated. But yeah, unless I can find out what I'm doing wrong,
> that's what I'll have to do.
>
>> Personally, much of my code is documented before any code is written
>> (it's called a "design"). It may or may not be a complete design,
>> depending on the complexity of the project. But the rough outlines are
>> there. Then I add any additional details as I go along.
>
> Okay, but what do you use to process your inline documentation?
> Design, documentation and tests first is a nice principle, but I've
> never seen a (non-trivial) project go from design to production without
> significant changes. Having to maintain separate documentation files in
> parallel to the source is asking for trouble, IMHO. But to each their own.
>
> Thanks,
> 5er
>
None of my projects require *significant* changes, unless it is due to
changes from the client. But then I started a long time ago (when
flowcharts were popular) and have quite a few projects under my belt.
And I do *complete* designs - not just some minimal scratches on a
notepad. It saves me a lot of time because I write code once and am
done. I don't need to keep going back to change things because of
something I didn't consider previously.
And no, maintaining separate documentation files is *critical* to a good
project. These are the documents the test group use to ensure the code
is written according to the documentation. It is also the first place
changes due to client requests or design deficiencies are applied. The
code is written to support the design.
The test group doesn't even look at the code. It looks at the
documentation to ensure the code runs according to the spec. It's
harder to separate coding from testing when you do both jobs, but it can
be done (and becomes easier with practice).
And no, I doubt very much anyone here uses PHP Documentor. And if it
ever was the "number one documentation generator for php", it still
wasn't very popular. You're one of the few people I've ever heard of who
uses it.
You can hang around all you want - no one's going to stop you. But
you're going to get better help through their support structure.
--
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex(at)attglobal(dot)net
==================
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182316 is a reply to message #182315] |
Sun, 28 July 2013 04:04 |
Fiver
Messages: 35
Registered: July 2013
Karma: 0
|
Member |
|
|
On 2013-07-28 04:59, Jerry Stuckle wrote:
> On 7/27/2013 10:45 PM, Fiver wrote:
>> On 2013-07-28 04:22, Jerry Stuckle wrote:
>>> Personally, much of my code is documented before any code is written
>>> (it's called a "design"). It may or may not be a complete design,
>>> depending on the complexity of the project. But the rough outlines are
>>> there. Then I add any additional details as I go along.
>>
>> Okay, but what do you use to process your inline documentation?
>> Design, documentation and tests first is a nice principle, but I've
>> never seen a (non-trivial) project go from design to production without
>> significant changes. Having to maintain separate documentation files in
>> parallel to the source is asking for trouble, IMHO. But to each their own.
> None of my projects require *significant* changes, unless it is due to
> changes from the client. But then I started a long time ago (when
> flowcharts were popular) and have quite a few projects under my belt.
> And I do *complete* designs - not just some minimal scratches on a
> notepad. It saves me a lot of time because I write code once and am
> done. I don't need to keep going back to change things because of
> something I didn't consider previously.
>
> And no, maintaining separate documentation files is *critical* to a good
> project. These are the documents the test group use to ensure the code
> is written according to the documentation. It is also the first place
> changes due to client requests or design deficiencies are applied. The
> code is written to support the design.
>
> The test group doesn't even look at the code. It looks at the
> documentation to ensure the code runs according to the spec. It's
> harder to separate coding from testing when you do both jobs, but it can
> be done (and becomes easier with practice).
You're clearly talking about an entirely different type of documentation
here. This sound more like a specification than what I had in mind: an
API reference. The documents you're describing answer the question "What
should this part do?", whereas what I'm talking about answers questions
like "What type of parameters does this method accept?" and "What's the
name of the method that returns a list of Foo objects?". A developer
reference. The typical case for inline documentation.
I have to admit that I'm tremendously impressed by the way your projects
work out. No significant changes; projects don't evolve over the years;
everything turning out as planned from the start - it sounds fantastic.
Practically unique in the world of large-scale software development. Kudos.
> And no, I doubt very much anyone here uses PHP Documentor. And if it
> ever was the "number one documentation generator for php", it still
> wasn't very popular. You're one of the few people I've ever heard of who
> uses it.
>
> You can hang around all you want - no one's going to stop you. But
> you're going to get better help through their support structure.
I'm beginning to suspect that you're right about that, judging from the
feedback I got so far. Nevertheless, I'll wait and see if I can get a
reply from someone who has actually used a tool to generate
documentation before. It's not that much of an outlandish idea.
If you're unsure of what I mean, here are some examples (using
PhpDocumentor/DocBlox):
http://framework.zend.com/apidoc/1.11/
http://apidocs.sugarcrm.com/api/6.7.1/pro/
http://pear.php.net/package/Mail/docs/latest/
http://roundcube.net/doc/phpdoc/
http://www.agavi.org/apidocs/index.html
You've probably heard of these projects before. You can find more
examples by searching the web for "This documentation was generated by
PhpDocumentor" or "This documentation was generated by DocBlox". If
you're entirely new to the concept, look up JavaDoc.
regards,
5er
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182318 is a reply to message #182316] |
Sun, 28 July 2013 12:05 |
Jerry Stuckle
Messages: 2598
Registered: September 2010
Karma: 0
|
Senior Member |
|
|
On 7/28/2013 12:04 AM, Fiver wrote:
> On 2013-07-28 04:59, Jerry Stuckle wrote:
>> On 7/27/2013 10:45 PM, Fiver wrote:
>>> On 2013-07-28 04:22, Jerry Stuckle wrote:
>>>> Personally, much of my code is documented before any code is written
>>>> (it's called a "design"). It may or may not be a complete design,
>>>> depending on the complexity of the project. But the rough outlines are
>>>> there. Then I add any additional details as I go along.
>>>
>>> Okay, but what do you use to process your inline documentation?
>>> Design, documentation and tests first is a nice principle, but I've
>>> never seen a (non-trivial) project go from design to production without
>>> significant changes. Having to maintain separate documentation files in
>>> parallel to the source is asking for trouble, IMHO. But to each their own.
>
>> None of my projects require *significant* changes, unless it is due to
>> changes from the client. But then I started a long time ago (when
>> flowcharts were popular) and have quite a few projects under my belt.
>> And I do *complete* designs - not just some minimal scratches on a
>> notepad. It saves me a lot of time because I write code once and am
>> done. I don't need to keep going back to change things because of
>> something I didn't consider previously.
>>
>> And no, maintaining separate documentation files is *critical* to a good
>> project. These are the documents the test group use to ensure the code
>> is written according to the documentation. It is also the first place
>> changes due to client requests or design deficiencies are applied. The
>> code is written to support the design.
>>
>> The test group doesn't even look at the code. It looks at the
>> documentation to ensure the code runs according to the spec. It's
>> harder to separate coding from testing when you do both jobs, but it can
>> be done (and becomes easier with practice).
>
> You're clearly talking about an entirely different type of documentation
> here. This sound more like a specification than what I had in mind: an
> API reference. The documents you're describing answer the question "What
> should this part do?", whereas what I'm talking about answers questions
> like "What type of parameters does this method accept?" and "What's the
> name of the method that returns a list of Foo objects?". A developer
> reference. The typical case for inline documentation.
>
Nope, part of the design also the API. It includes input parameters,
what it does, and return values. It makes for great inline developer
documentation.
> I have to admit that I'm tremendously impressed by the way your projects
> work out. No significant changes; projects don't evolve over the years;
> everything turning out as planned from the start - it sounds fantastic.
> Practically unique in the world of large-scale software development. Kudos.
>
As I said - no significant changes unless they come from the client.
When the client makes changes, those changes are applied to the
documentation first. Then you know exactly what needs to be changed in
the code.
>> And no, I doubt very much anyone here uses PHP Documentor. And if it
>> ever was the "number one documentation generator for php", it still
>> wasn't very popular. You're one of the few people I've ever heard of who
>> uses it.
>>
>> You can hang around all you want - no one's going to stop you. But
>> you're going to get better help through their support structure.
>
> I'm beginning to suspect that you're right about that, judging from the
> feedback I got so far. Nevertheless, I'll wait and see if I can get a
> reply from someone who has actually used a tool to generate
> documentation before. It's not that much of an outlandish idea.
>
I have tried tools to generate documentation. All of them have done a
poor job compared to proper design documentation.
> If you're unsure of what I mean, here are some examples (using
> PhpDocumentor/DocBlox):
>
> http://framework.zend.com/apidoc/1.11/
> http://apidocs.sugarcrm.com/api/6.7.1/pro/
> http://pear.php.net/package/Mail/docs/latest/
> http://roundcube.net/doc/phpdoc/
> http://www.agavi.org/apidocs/index.html
>
> You've probably heard of these projects before. You can find more
> examples by searching the web for "This documentation was generated by
> PhpDocumentor" or "This documentation was generated by DocBlox". If
> you're entirely new to the concept, look up JavaDoc.
>
> regards,
> 5er
>
Oh, I'm familiar with documentation generators. I'm also aware most PHP
programmers (and a lot of programmers in general) are "code and go".
They don't create designs ahead of time. As a result, they spend a lot
of time rewriting code and experimenting to try to get things to work.
Designing the system up front takes time - but not nearly as much as
trying to design around code you've already written.
I've seen the same on some large (multiple programmer) projects. I've
even had managers tell me "If my programmers aren't writing code, they
aren't being productive".
It's a lot like telling a carpenter "Build me a house" without hiring an
architect first. But programmers seem to think it's ok to waste a lot
of time.
--
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex(at)attglobal(dot)net
==================
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182319 is a reply to message #182318] |
Sun, 28 July 2013 12:23 |
Tim Streater
Messages: 328
Registered: September 2010
Karma: 0
|
Senior Member |
|
|
In article <kt311j$9me$1(at)dont-email(dot)me>,
Jerry Stuckle <jstucklex(at)attglobal(dot)net> wrote:
> I've seen the same on some large (multiple programmer) projects. I've
> even had managers tell me "If my programmers aren't writing code, they
> aren't being productive".
Then refer them to "The Mythical Month Month", chapter 1.
--
Tim
"That excessive bail ought not to be required, nor excessive fines imposed,
nor cruel and unusual punishments inflicted" -- Bill of Rights 1689
|
|
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182324 is a reply to message #182322] |
Sun, 28 July 2013 14:24 |
Tim Streater
Messages: 328
Registered: September 2010
Karma: 0
|
Senior Member |
|
|
In article <kt36dv$4g8$1(at)dont-email(dot)me>,
Jerry Stuckle <jstucklex(at)attglobal(dot)net> wrote:
> On 7/28/2013 8:23 AM, Tim Streater wrote:
>> In article <kt311j$9me$1(at)dont-email(dot)me>,
>> Jerry Stuckle <jstucklex(at)attglobal(dot)net> wrote:
>>
>>> I've seen the same on some large (multiple programmer) projects. I've
>>> even had managers tell me "If my programmers aren't writing code, they
>>> aren't being productive".
>>
>> Then refer them to "The Mythical Month Month", chapter 1.
>>
>
> Yup, and it's so true.
Ooops, should have been "... Man Month ...". Sorry.
--
Tim
"That excessive bail ought not to be required, nor excessive fines imposed,
nor cruel and unusual punishments inflicted" -- Bill of Rights 1689
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182325 is a reply to message #182316] |
Sun, 28 July 2013 14:36 |
Scott Johnson
Messages: 196
Registered: January 2012
Karma: 0
|
Senior Member |
|
|
On 7/27/2013 9:04 PM, Fiver wrote:
> On 2013-07-28 04:59, Jerry Stuckle wrote:
>> On 7/27/2013 10:45 PM, Fiver wrote:
>>> On 2013-07-28 04:22, Jerry Stuckle wrote:
>>>> Personally, much of my code is documented before any code is written
>>>> (it's called a "design"). It may or may not be a complete design,
>>>> depending on the complexity of the project. But the rough outlines are
>>>> there. Then I add any additional details as I go along.
>>>
>>> Okay, but what do you use to process your inline documentation?
>>> Design, documentation and tests first is a nice principle, but I've
>>> never seen a (non-trivial) project go from design to production without
>>> significant changes. Having to maintain separate documentation files in
>>> parallel to the source is asking for trouble, IMHO. But to each their own.
>
>> None of my projects require *significant* changes, unless it is due to
>> changes from the client. But then I started a long time ago (when
>> flowcharts were popular) and have quite a few projects under my belt.
>> And I do *complete* designs - not just some minimal scratches on a
>> notepad. It saves me a lot of time because I write code once and am
>> done. I don't need to keep going back to change things because of
>> something I didn't consider previously.
>>
>> And no, maintaining separate documentation files is *critical* to a good
>> project. These are the documents the test group use to ensure the code
>> is written according to the documentation. It is also the first place
>> changes due to client requests or design deficiencies are applied. The
>> code is written to support the design.
>>
>> The test group doesn't even look at the code. It looks at the
>> documentation to ensure the code runs according to the spec. It's
>> harder to separate coding from testing when you do both jobs, but it can
>> be done (and becomes easier with practice).
>
> You're clearly talking about an entirely different type of documentation
> here. This sound more like a specification than what I had in mind: an
> API reference. The documents you're describing answer the question "What
> should this part do?", whereas what I'm talking about answers questions
> like "What type of parameters does this method accept?" and "What's the
> name of the method that returns a list of Foo objects?". A developer
> reference. The typical case for inline documentation.
>
> I have to admit that I'm tremendously impressed by the way your projects
> work out. No significant changes; projects don't evolve over the years;
> everything turning out as planned from the start - it sounds fantastic.
> Practically unique in the world of large-scale software development. Kudos.
>
>> And no, I doubt very much anyone here uses PHP Documentor. And if it
>> ever was the "number one documentation generator for php", it still
>> wasn't very popular. You're one of the few people I've ever heard of who
>> uses it.
>>
>> You can hang around all you want - no one's going to stop you. But
>> you're going to get better help through their support structure.
>
> I'm beginning to suspect that you're right about that, judging from the
> feedback I got so far. Nevertheless, I'll wait and see if I can get a
> reply from someone who has actually used a tool to generate
> documentation before. It's not that much of an outlandish idea.
>
> If you're unsure of what I mean, here are some examples (using
> PhpDocumentor/DocBlox):
>
> http://framework.zend.com/apidoc/1.11/
> http://apidocs.sugarcrm.com/api/6.7.1/pro/
> http://pear.php.net/package/Mail/docs/latest/
> http://roundcube.net/doc/phpdoc/
> http://www.agavi.org/apidocs/index.html
>
> You've probably heard of these projects before. You can find more
> examples by searching the web for "This documentation was generated by
> PhpDocumentor" or "This documentation was generated by DocBlox". If
> you're entirely new to the concept, look up JavaDoc.
>
> regards,
> 5er
>
Wow fiver.
Jerry simply gave you a reference of where you 'might' find better
advice and you fight him at every turn to the point of being sarcastic.
He never said you where stupid or would not find help here, just gave
you a suggestion.
Makes me think now if anyone had advice on how to fix your issue you
might fight them as well.
Good luck.
Scotty
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182330 is a reply to message #182325] |
Sun, 28 July 2013 16:38 |
Fiver
Messages: 35
Registered: July 2013
Karma: 0
|
Member |
|
|
On 2013-07-28 16:36, Scott Johnson wrote:
> Wow fiver.
>
> Jerry simply gave you a reference of where you 'might' find better
> advice and you fight him at every turn to the point of being sarcastic.
>
> He never said you where stupid or would not find help here, just gave
> you a suggestion.
>
> Makes me think now if anyone had advice on how to fix your issue you
> might fight them as well.
Yes, that last message did turn out more aggressive than I had intended.
My apologies to Jerry; it had been a very long and frustrating day. In
my defense, I did not need to be told how to contact the PhpDocumentor
developers; I already knew that. I've also spent over an hour digging
through their bug tracker.
What annoyed me was being lectured on how to properly design a project.
I don't agree that having the API documentation separate from the source
is a good idea, and I'm certainly not alone in that opinion. I also have
my reservations about the claim that large software projects can be
designed perfectly from the start and will never deviate from the
original plan, even when you exclude client requests. Such a claim
stands against everything ever written about software development and
project management - including The Mythical Man-Month - and also against
my 20+ years of experience in the field. In any non-trivial project
(months to years), the original design will evolve; external tools will
be updated or exchanged; unexpected problems will be discovered;
previously unknown data errors will have to be worked around; APIs will
drift and expand; hardware will change; newly discovered security
threats will have to be avoided; new techniques will become available;
new developers will enter and bring their knowlege into the project;
etc. If it was feasible to anticipate all those factors from the outset,
the job of a project manager would be reduced to that of an overseer.
Methods like agile development wouldn't exist, and hundreds of book
authors would be out of a job. I don't know, maybe Jerry is the
exception to the rule. For everybody else, though, it's a good idea to
expect changes and deviations during the course of a project. The
development workflow should reflect that, and having the API
documentation close to the source is just one of the tools used to
accomplish that.
regards,
5er
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182337 is a reply to message #182330] |
Sun, 28 July 2013 19:01 |
Jerry Stuckle
Messages: 2598
Registered: September 2010
Karma: 0
|
Senior Member |
|
|
On 7/28/2013 12:38 PM, Fiver wrote:
> On 2013-07-28 16:36, Scott Johnson wrote:
>> Wow fiver.
>>
>> Jerry simply gave you a reference of where you 'might' find better
>> advice and you fight him at every turn to the point of being sarcastic.
>>
>> He never said you where stupid or would not find help here, just gave
>> you a suggestion.
>>
>> Makes me think now if anyone had advice on how to fix your issue you
>> might fight them as well.
>
> Yes, that last message did turn out more aggressive than I had intended.
> My apologies to Jerry; it had been a very long and frustrating day. In
> my defense, I did not need to be told how to contact the PhpDocumentor
> developers; I already knew that. I've also spent over an hour digging
> through their bug tracker.
>
> What annoyed me was being lectured on how to properly design a project.
> I don't agree that having the API documentation separate from the source
> is a good idea, and I'm certainly not alone in that opinion. I also have
> my reservations about the claim that large software projects can be
> designed perfectly from the start and will never deviate from the
> original plan, even when you exclude client requests. Such a claim
> stands against everything ever written about software development and
> project management - including The Mythical Man-Month - and also against
> my 20+ years of experience in the field. In any non-trivial project
> (months to years), the original design will evolve; external tools will
> be updated or exchanged; unexpected problems will be discovered;
> previously unknown data errors will have to be worked around; APIs will
> drift and expand; hardware will change; newly discovered security
> threats will have to be avoided; new techniques will become available;
> new developers will enter and bring their knowlege into the project;
> etc. If it was feasible to anticipate all those factors from the outset,
> the job of a project manager would be reduced to that of an overseer.
> Methods like agile development wouldn't exist, and hundreds of book
> authors would be out of a job. I don't know, maybe Jerry is the
> exception to the rule. For everybody else, though, it's a good idea to
> expect changes and deviations during the course of a project. The
> development workflow should reflect that, and having the API
> documentation close to the source is just one of the tools used to
> accomplish that.
>
> regards,
> 5er
>
Maybe you don't agree - but I've been doing it for over 40 years, and in
that time I've worked on some very large projects - multiple
programmers, even several designers working together.
Changes in external tools and hardware are some of the client
requirement changes I talk about. Proper design and testing will
eliminate all security threats (and many - but not all - other bugs).
And new developers can bring additional knowledge to the task, but if
the original developers are experienced and knowledgeable, the design
will not change.
As for documentation being independent of source code - this is critical
for good QA. Testing is done to the DESIGN - not to the CODE. Ideally,
testers won't even have the source for the code being tested (I know
that's not really possible in PHP). Otherwise, the tester is going to
write tests based on the code that exists, not what it's supposed to do.
A lot of bugs are missed this way.
My job as a project manager is much more than just overseeing things.
It includes following the project's progress, keeping in touch with the
client, making changes in the documentation as necessary and ensuring
those changes are communicated to the developers; monitoring the
timeline and continually estimating project costs and projected
completion date - a lot of work.
Oh, and BTW - the documentation system we use is based on SQL databases.
One of the things in the database is a "Calls" column. When we are
designing method "a" and it calls method "b", method "b" is
automatically updated with the fact that "a" is calling it. That way if
we do have to change the interface, we know *exactly* which methods need
to be addressed (and tested again). You can't do that in source code
comments, either.
I always expect change and deviation in a project. That's why keeping
the documentation separate from the code is so important.
--
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex(at)attglobal(dot)net
==================
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182343 is a reply to message #182308] |
Mon, 29 July 2013 07:27 |
Goran
Messages: 38
Registered: January 2011
Karma: 0
|
Member |
|
|
This story sounds so familiar to me... I took the same adventure and
give up:( Also, filled few tickets but nothing significantly changed
This product is obviously in very unstable phase (from installation to
usage) so I suggest you to go for alternative. Just curious, did you
looked into apigen?
|
|
|
|
| Re: Major trouble with PhpDocumentor [message #182348 is a reply to message #182343] |
Mon, 29 July 2013 19:29 |
Fiver
Messages: 35
Registered: July 2013
Karma: 0
|
Member |
|
|
On 2013-07-29 09:27, Goran wrote:
> This story sounds so familiar to me... I took the same adventure and
> give up:( Also, filled few tickets but nothing significantly changed
>
> This product is obviously in very unstable phase (from installation to
> usage) so I suggest you to go for alternative. Just curious, did you
> looked into apigen?
No, I hadn't heard of it before. ApiGen is indeed very interesting. It
installed and ran fine (after a minor path adjustment). The generated
HTML from the default template also looks a lot cleaner than
PhpDocumentor's. The only drawback is that it apparently cannot be used
to document files (simple PHP scripts), only namespaces, classes,
methods, functions and constants.
I think I'll let this rest for a while and give the PhpDocumentor
developers some time to iron out the bugs in the beta. At least I have a
suitable fallback in Apigen now.
Thank you,
5er
|
|
|
|
Calendar
Search
Help
Members
Register
Login
Home
]