Ticket #1725 (closed todo: fixed)

Opened 11 years ago

Last modified 11 years ago

tools/build/headerizer.pl: documentation is confusing

Reported by: jkeenan Owned by: jkeenan
Priority: normal Milestone:
Component: docs Version: 2.6.0
Severity: medium Keywords:
Cc: mikehh, petdance Language:
Patch status: applied Platform:


The POD for this program has two sections called NAME and two called SYNOPSIS. The material in DESCRIPTION, DIRECTIVES and perhaps some other sections would be better combined into one =head1.

$ grep -nE '^=head(1|2)' tools/build/headerizer.pl 
5:=head1 NAME
10:=head1 SYNOPSIS
20:=head1 TODO
26:=head1 NOTES
69:=head1 FUNCTIONS
71:=head2 extract_function_declaration_and_update_source( $cfile_name )
446:=head1 NAME
450:=head1 SYNOPSIS
457:=head1 DIRECTIVES

So, a fresh look at this file's documentation is in order.

Thank you very much.


Change History

  Changed 11 years ago by jkeenan

  • owner set to jkeenan
  • status changed from new to assigned

Created tt1725_headerizer_documentation branch in repository to work on this ticket. So as to better understand what lib/Parrot/Headerizer.pm and tools/build/headerizer.pl do, I will write some tests, then move on to documentation.

follow-up: ↓ 3   Changed 11 years ago by jkeenan

As I indicated on #parrotsketch on Aug 17, I'm not going to pursue the line of approach described in my previous post at this time. So I've deleted the tt1725_headerizer_documentation branch. I have, however, edited the POD in tools/build/headerizer.pl and committed those changes in r48588.

Andy L, Mike, other interested parties: Could you call perldoc tools/build/headerizer.pl and see how you like the results?

If I hear no objections, I'll close this ticket in the middle of the coming week. Thank you very much.


in reply to: ↑ 2   Changed 11 years ago by jkeenan

  • status changed from assigned to closed
  • resolution set to fixed
  • patch set to applied

Replying to jkeenan:

If I hear no objections, I'll close this ticket in the middle of the coming week. Thank you very much.

No objections recorded. Closing ticket.

Note: See TracTickets for help on using tickets.