https://github.com/pvande/yard-perl-plugin

Developing a Perl documentation tool... in Ruby
https://github.com/pvande/yard-perl-plugin

documentation-tool perl

Last synced: over 1 year ago
JSON representation

Developing a Perl documentation tool... in Ruby

• Host: GitHub
• URL: https://github.com/pvande/yard-perl-plugin
• Owner: pvande
• Created: 2010-04-06T07:55:23.000Z (about 16 years ago)
• Default Branch: master
• Last Pushed: 2021-08-13T22:12:21.000Z (almost 5 years ago)
• Last Synced: 2025-02-28T08:45:55.632Z (over 1 year ago)
• Topics: documentation-tool, perl
• Language: Ruby
• Homepage:
• Size: 145 KB
• Stars: 11
• Watchers: 5
• Forks: 7
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
OH SO BETA WARNING

==================

This is wildly speculative software.  It works in a few cases.  It breaks in

all the rest.  USE AT YOUR OWN RISK.  Not valid with any other offer.  Void

where prohibited.

Pwa?

====

Here's what I've been doing:

    $ cd perl-project

    $ yardoc -e ../yard-perl-plugin/lib/yard-perl-plugin.rb lib/**/*.pm

YARD then transforms my ragtag bunch of (regularly formatted) Perl modules

into fine, high-quality documentation.

At present, this module will:

 * Work with YARD 0.6 -- and likely beyond!

 * Parse most Perl!

   * Support for this is provided by Textpow, via the TextMate Perl.plist

   (slightly modified)

 * Parse a package declaration

 * Parse a named sub declaration

 * Parse documentation comments

 * Handle subroutine visibility

   * Subroutines declared before a 'use namespace::clean' are marked private

   * Subroutines named with a leading '_' are marked protected

 * Handle subroutine parameters

   * Parameters are inferred from the first few assignments of the subroutine

   * Assignments that `shift` off @_ will populate a single parameter

   * Assigning from @_ in list context will further populate parameters

 * Handle method scope

   * If the first parameter name is 'self' or 'instance', instance scope is

   assumed

   * If the first parameter name is 'class' or 'package', class scope is

   assumed

   * If the first parameter name is 'receiver', 'invocant', or

   'class\_or_self', it is assumed the method may be called as either a class

   or instance method

   * If the first parameter name cannot be recognized, instance scope is assumed

   * **It is recognized that this is sub-optimal; suggestions welcomed**

 * Support the @group tag

   * This tag applies to all method declarations following, until the next

   @group tag or a corollary @endgroup tag

   * Methods in a group are given their own heading in the documentation

     * This can be used to emulate, for example, a documented export list

 * Provide syntax highlighting for HTML output

   * Support for this is provided by Textpow, via the TextMate Perl.plist

   (slightly modified)

This module *won't*:

 * Do much else