Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.php > #10259 > unrolled thread

Major trouble with PhpDocumentor

Back to article view | Back to comp.lang.php

Contents

  Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 03:25 +0200
    Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-27 21:38 -0400
      Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 04:14 +0200
        Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-27 22:22 -0400
          Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 04:45 +0200
            Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-27 22:59 -0400
              Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 06:04 +0200
                Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-28 08:05 -0400
                  Re: Major trouble with PhpDocumentor Tim Streater <timstreater@greenbee.net> - 2013-07-28 13:23 +0100
                    Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-28 09:37 -0400
                      Re: Major trouble with PhpDocumentor Tim Streater <timstreater@greenbee.net> - 2013-07-28 15:24 +0100
                Re: Major trouble with PhpDocumentor Scott Johnson <noonehome@chalupasworld.com> - 2013-07-28 07:36 -0700
                  Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 18:38 +0200
                    Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-28 15:01 -0400
    Re: Major trouble with PhpDocumentor Goran <goran@nospam.com> - 2013-07-29 09:27 +0200
      Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-29 21:29 +0200

#10259 — Major trouble with PhpDocumentor

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

[toc] | [next] | [standalone]

#10260

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@attglobal.net
==================

[toc] | [prev] | [next] | [standalone]

#10263

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

[toc] | [prev] | [next] | [standalone]

#10264

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@attglobal.net
==================

[toc] | [prev] | [next] | [standalone]

#10265

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

[toc] | [prev] | [next] | [standalone]

#10266

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@attglobal.net
==================

[toc] | [prev] | [next] | [standalone]

#10267

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

[toc] | [prev] | [next] | [standalone]

#10269

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@attglobal.net
==================

[toc] | [prev] | [next] | [standalone]

#10270

In article <kt311j$9me$1@dont-email.me>,
 Jerry Stuckle <jstucklex@attglobal.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

[toc] | [prev] | [next] | [standalone]

#10273

On 7/28/2013 8:23 AM, Tim Streater wrote:
> In article <kt311j$9me$1@dont-email.me>,
> Jerry Stuckle <jstucklex@attglobal.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.


-- 
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex@attglobal.net
==================

[toc] | [prev] | [next] | [standalone]

#10275

In article <kt36dv$4g8$1@dont-email.me>,
 Jerry Stuckle <jstucklex@attglobal.net> wrote:

> On 7/28/2013 8:23 AM, Tim Streater wrote:
> > In article <kt311j$9me$1@dont-email.me>,
> > Jerry Stuckle <jstucklex@attglobal.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

[toc] | [prev] | [next] | [standalone]

#10276

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

[toc] | [prev] | [next] | [standalone]

#10281

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

[toc] | [prev] | [next] | [standalone]

#10288

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@attglobal.net
==================

[toc] | [prev] | [next] | [standalone]

#10294

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?

[toc] | [prev] | [next] | [standalone]

#10299

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

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.php

csiph-web