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

Groups > comp.lang.php > #10266

Re: Major trouble with PhpDocumentor

Show all headers | View raw

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

Back to comp.lang.php | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

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

csiph-web