283029 - Update to add POD how-to for developer's guide.

Status: RESOLVED FIXED

(Bugzilla :: bugzilla.org, enhancement)

Description

[Kevin Benton]

Update to add POD how-to for developer's guide.

Comment 1

[Kevin Benton]

Attachment: POD update recommendation

Comment 2

[Max Kanat-Alexander]

Comment on attachment 175015 [details] [diff] [review]
POD update recommendation

Cool, looks pretty good.

Also, add a link to the Bugzilla::DB POD, which is probably the best POD we
have at the moment, as an example of what a real working POD looks like.

Bugzilla POD entries don't usually have CONTRIBUTORS or LICENSE, and they don't
always have NOTES or SEE ALSO.

They almost always have METHODS and CLASS FUNCTIONS, or at least they should.
:-)

Comment 3

[Kevin Benton]

Attachment: Revised per Max's comments, but see my comments to this attachment for more info.

Max - I chose not to put the link to a module for POD examples because as you
suggested, the Bugzilla/DB.pm POD is all at the end of the file rather then
being embedded in the source.  I have two module updates coming up, probably
later today for Bugzilla/Flag.pm and Bugzilla/FlagType.pm which do have in-line
POD and I think will demonstrate how to use POD far better than DB.pm does.

Comment 4

[Max Kanat-Alexander]

OK, I'm going to hold off a bit on this review until I see the Flag.pm POD
stuff, then. I'm definitely very excited about having good and standardized API
docs, though. :-)

Comment 5

[Kevin Benton]

Comment on attachment 175151 [details] [diff] [review]
Revised per Max's comments, but see my comments to this attachment for more info.

Additional updates to follow.

Comment 6

[Kevin Benton]

Attachment: includes section to make POD private (non-displayed)

Comment 7

[Kevin Benton]

Comment on attachment 175301 [details] [diff] [review]
includes section to make POD private (non-displayed)

One more update coming up...

Comment 8

[Kevin Benton]

Attachment: POD how-to for Bugzilla Modules - multiple updates.

Comment 9

[Kevin Benton]

Hi Max - this is waiting on your review :)

Comment 10

[Max Kanat-Alexander]

Comment on attachment 175310 [details] [diff] [review]
POD how-to for Bugzilla Modules - multiple updates.

Yeah, I like this. :-)

Two comments:

1) Isn't it "undocumented", not "private" for those begin/end blocks?

2) Give it its own <h2> -- I think it's long enough. :-)

Comment 11

[Dave Miller [:justdave]]

(In reply to comment #10)

> 1) Isn't it "undocumented", not "private" for those begin/end blocks?

I don't think it matters.  Neither format exists, so either one will hide it. :)
 BTW, the perlpodspec man page seems to indicate that other pod commands inside
a =begin/=end block will cause an error in the pod processor unless the format
name begins with a :, in which case a processor which doesn't understand it
would treat it like normal instead of hiding it.

> 2) Give it its own <h2> -- I think it's long enough. :-)

It has one.  There was already a POD section there (which was only two or three
lines long) that he extended.

Comment 12

[Dave Miller [:justdave]]

Checking in docs/developer.html.tmpl;
/cvsroot/mozilla-org/html/projects/bugzilla/docs/developer.html.tmpl,v  <-- 
developer.html.tmpl
new revision: 1.7; previous revision: 1.6
done

Comment 13

[Kevin Benton]

Max/Dave - I chose "private" over "undocumented" because it's not undocumented -
we're documenting it right there if someone is looking at the code.  On the
other hand, it is definitely not intended for "general public use" - therefore
it's private.  Also, many who program class-level languages like C++ are used to
"public" versus "private" functions - hence, the use of the word private over
undocumented.

Dave - when I looked at perlpodspec, I found out that the colon tells the POD
processor that the data region between the =begin and =end lines is to be
handled by a specific type of processor but only if there is a colon there. 
Since I don't put a colon there, the region is seen as data.  So, perldoc
ignores the section between the =begin and =end.  OTOH, Perl sees the =cut in
the middle and starts processing code again till it sees another POD tag.

Comment 14

[Kevin Benton]

(In reply to comment #12)
> Checking in docs/developer.html.tmpl;
> /cvsroot/mozilla-org/html/projects/bugzilla/docs/developer.html.tmpl,v  <-- 
> developer.html.tmpl
> new revision: 1.7; previous revision: 1.6
> done
> 

Grrr - I missed a spelling mistake - fucntions was spelled incorrectly in my
document.  I never ran my patch through a spell checker.  Dave - did you catch
that one?