| 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:
|
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
==================
|
|
|
|
Calendar
Search
Help
Members
Register
Login
Home
]