Ticket #1725 (closed todo: fixed)

Opened 4 years ago

Last modified 4 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:

Description

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
14:=head1 DESCRIPTION
20:=head1 TODO
26:=head1 NOTES
35:=head1 COMMAND-LINE OPTIONS
45:=head1 COMMAND-LINE ARGUMENTS
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.

kid51

Change History

  Changed 4 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 4 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.

kid51

in reply to: ↑ 2   Changed 4 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.