Item14237: Added PERLDOC macro

Unified and simplified way to create links to in-code documentation
inluding anchoring to method/attribute subsections.

core/data/System/VarPERLDOC.txt

@@ -0,0 +1,33 @@
+%META:TOPICINFO{author="ProjectContributor" date="1506731777" format="1.1" version="1"}%
+%META:TOPICPARENT{name="Macros"}%
+---+ PERLDOC -- generate a link to code documentation
+Generates a link to in-code documentation. Takes following parameters:
+
+   | *Parameter* | *Description* | *Default* |
+   | ="Foswiki::ModuleName"= | Module name | =Foswiki= |
+   | =method= | Name of a method to point to | |
+   | =attr= or =attribute= | Name of an attribute to point to | |
+   | =text= | Text to be displayed instead of default | |
+
+If either =method= or =attr= is used the generated link will contain anchor
+pointing to corresponding sub-section in the documentation. Note that if both
+parameters are used then =method= has priority over =attr=.
+
+Default text generated for the link consist of module name followed by a double
+colon and the method or attribute name if corresponding parameters are present;
+for methods parenthesis are appended at the end. If this representation is not
+desirable then parameter =text= must be set.
+
+*Note:* This macro is fully functional only when =USE_LEXICAL_PARSER= in
+%PERLDOC{"Foswiki::IncludeHandlers::doc"}% constant is set to a _true_ value.
+Otherwise linking to subsections won't work.
+---++ Examples
+   * =%<nop>PERLDOC{"Foswiki::App"}%= displays as: %PERLDOC{"Foswiki::Config"}%
+   * =%<nop>PERLDOC{"Foswiki::App" method="handleRequest"}%= displays as: %PERLDOC{"Foswiki::App" method="handleRequest"}%
+   * =%<nop>PERLDOC{"Foswiki::App" method="create" text="see app's =create()= method"}%= 
+     displays as:
+     %PERLDOC{"Foswiki::App" method="create" text="see app's =create()= method"}%
+%STOPINCLUDE%
+---++ Related
+ [[VarINCLUDE][INCLUDE]]
+

core/lib/Foswiki/IncludeHandlers/doc.pm

@@ -241,20 +241,20 @@ sub INCLUDE {
 
                             my $pluggable = "";
                             if ( $methodText =~ /^\W*(?<methodName>\w+)\b/ ) {
+                                my $methodName = $+{methodName};
 
                                 # TODO Replace word Pluggable with a link to
                                 # extensions documentaion when ready.
                                 $pluggable =
                                   $Foswiki::ExtManager::pluggables{$class}
-                                  { $+{methodName} } ? "Pluggable " : "";
+                                  {$methodName} ? "Pluggable " : "";
 
                                 # SMELL methodName with underscores generates
                                 # bad anchor name which is getting split by the
                                 # first _. Should anchor name handling be fixed?
-                                $anchor = "#"
-                                  . $methodAccess
-                                  . $methodType
-                                  . $+{methodName} . "\n";
+                                $anchor =
+                                  _makeAnchor( $app, $methodType, $methodName )
+                                  . "\n";
                             }
                             $pod .=
 "\n$anchor$secDef =${pluggable}[[$methodAccess$methodType]]= ==$methodTextEncoded==\n";
@@ -578,12 +578,26 @@ sub _doclink {
       ) . $formatChar;
 }
 
+sub _makeAnchor {
+    my $app = shift;
+
+    # type is either method or attr/attribute; case is irrelevant
+    my ( $type, $name ) = @_;
+
+    $type =~ s/^attribute$/attr/i;
+    $type = ucfirst( lc($type) );
+    $name =~ s/_+//;
+    $name = join( "", map { ucfirst } split /_+/, $name );
+
+    return "#${type}${name}";
+}
+
 1;
 
 __END__
 Foswiki - The Free and Open Source Wiki, http://foswiki.org/
 
-Copyright (C) 2008-2012 Foswiki Contributors. Foswiki Contributors
+Copyright (C) 2008-2017 Foswiki Contributors. Foswiki Contributors
 are listed in the AUTHORS file in the root of this distribution.
 NOTE: Please extend that file, not this notice.
 

core/lib/Foswiki/Macros.pm

@@ -915,6 +915,7 @@ sub _registerDefaultMacros {
         META      => undef, # deprecated
         METASEARCH           => undef,    # deprecated
         NONCE                => undef,
+        PERLDOC              => undef,
         PERLDEPENDENCYREPORT => undef,
         NOP =>
 

core/lib/Foswiki/Macros/PERLDOC.pm

@@ -0,0 +1,66 @@
+# See bottom of file for license and copyright information
+package Foswiki::Macros::PERLDOC;
+
+use Try::Tiny;
+use Data::Dumper;
+
+use Foswiki::Class qw(app);
+extends qw<Foswiki::Object>;
+with qw<Foswiki::Macro>;
+
+sub expand {
+    my $this = shift;
+    my ( $params, $topicObject ) = @_;
+
+    Foswiki::load_package('Foswiki::IncludeHandlers::doc');
+
+    #my $anchor = Foswiki::IncludeHandlers::doc::_makeAnchor
+
+    my $result = "";
+
+    my $module = $params->{_DEFAULT} || 'Foswiki';
+    my ( $anchor, $type, $linkText ) = ( "", "", $module );
+
+  TYPE: foreach $type (qw<method attr attribute>) {
+        if ( defined $params->{$type} ) {
+            $anchor =
+              Foswiki::IncludeHandlers::doc::_makeAnchor( $this->app,
+                $type => $params->{$type} );
+            $linkText = $module . "::" . $params->{$type};
+            $linkText .= "()" if ( $type eq 'method' );
+            $linkText = "$linkText";
+            last TYPE;
+        }
+    }
+
+    $linkText = $params->{text} if $params->{text};
+
+    $result .=
+        "[[%SCRIPTURL{view}%/%SYSTEMWEB%/PerlDoc?module="
+      . $module
+      . $anchor . "]["
+      . $linkText . "]]";
+
+    return $result;
+}
+
+1;
+
+__END__
+Foswiki - The Free and Open Source Wiki, http://foswiki.org/
+
+Copyright (C) 2017 Foswiki Contributors. Foswiki Contributors
+are listed in the AUTHORS file in the root of this distribution.
+NOTE: Please extend that file, not this notice.
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version. For
+more details read LICENSE in the root of this distribution.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+As per the GPL, removal of this notice is prohibited.