search

kentfredric / ideas

Draft ideas for things that are more organised and feedbacky than gists with mkdn as default
1 stars 0 forks source link

Comment::Signatures #5

Open kentfredric opened 9 years ago

kentfredric commented 9 years ago

Objective

Fast/Tidy/Simple annotations of method/function/classmethod signatures for documentation purposes with a small amount of transpilation potential

Things that are broken

POD

  1. =head1 methodname(foo) will give you headings that are impossible to link to

  2. You can't have a =head1 without a following blank line, and a following =cut => ewww 

    =head1 subfoo
subfoo(foo)
=cut

    this is bulky and makes reading the source horrible

  3. =head1 is not indicative of anything in POD semantically, its just a heading, so intelligent scraping is right out
  4. Indicating whether a sub is a function/method/class method further complicates matters in terms of visual clarity

These factors all amount to people not wanting to document functions in-place because of the clutter it adds to code reading.

Idea

#& $class->method( $args )
#& $instance->method( $args )
#& ->method($args)
#& function($args)
  1. Its just a comment, and only takes up one line, no POD magic required.
  2. No requirements to have perl 5.22
  3. Magic token is "#&\s+"
  4. $class-> is parsed and states "This method can be called as a class method"
  5. $instance-> is parsed and states "This method can be called on an instance"
  6. -> is parsed and assumes it works as both ( eg: #& ->method )
  7. lack of a prefix containing '->' assumes its a function
  8. characters from either leading '->' or non-prefixed whitespace up to the first whitespace or "(" character is assumed to be "The subname"
  9. characters after the first whitespace or "(" is assumed to be "the signature"
  10. The signature itself is freeform at this time
  11. Purpose is primarily to extract these forms quickly and easily so that they may be re-written into other forms / handed over to something more interesting.

    Future

  12. Extracted signatures could be used to instrument code in some sort of compile phase where the signatures get expanded into perl-5.6 compatible code. ( However, that is outside the scope of this module )
  13. Extracted signatures could be rewritten in various POD notations optimising for metacpan, where the "invocant" and "signature" part are stripped from the header name, but are retained in the sections text ( like in an indented code block )
  14. Extracted signatures can be aggregated as-is to form cheat sheets.
kentfredric commented 9 years ago

Example of what application looks like: https://github.com/kentnl/Gentoo-XML/blob/5e6414493a070864b5b9bd6a24c446dcd7eee663/lib/Gentoo/XML/Node.pm