Issue with producing a md docs if package have a license info at top.

[lwasylow]

When parsing the body seems like apache license info on top in certain scenarios causing issue e.g. attached (shortend version)

create or replace package ut authid current_user as

  /*
  utPLSQL - Version 3
  Copyright 2016 - 2017 utPLSQL Project

  Licensed under the Apache License, Version 2.0 (the "License"):
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
  */

  /**
   * Helper procedure to reset NLS session parameter to it's original state.
   * It needs to be called after refcursor is open in order restore the original session state and keep the NLS date setting at default.
    *
   * @example
   * ut_expectation := expect()
   *
   *
   * @author utPLSQL
   * @created 09-Jan-2017
   */
  procedure reset_nls;

end ut;
/

create or replace package body ut is

  /*
  utPLSQL - Version 3
  Copyright 2016 - 2017 utPLSQL Project

  Licensed under the Apache License, Version 2.0 (the "License"):
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
  */

  g_nls_date_format varchar2(4000);

  procedure raise_if_packages_invalidated is
    e_package_invalidated exception;
    pragma exception_init (e_package_invalidated, -04068);
  begin
    if ut_expectation_processor.invalidation_exception_found() then
      ut_expectation_processor.reset_invalidation_exception();
      raise e_package_invalidated;
    end if;
  end;

    procedure reset_nls is
  begin
    if g_nls_date_format is not null then
      execute immediate 'alter session set nls_date_format = '''||g_nls_date_format||'''';
    end if;
    g_nls_date_format := null;
  end;

end ut;
/

produces markdown as follow:

UT

• Variables

• Exceptions

• RESET_NLS Procedure

Variables

Name	Code	Description
g_nls_date_format	g_nls_date_format varchar2(4000);
pragma	pragma exception_init (e_package_invalidated, -04068);
raise	raise e_package_invalidated;
end	end if;
end	end ut;

Exceptions

Name	Code	Description
g_nls_date_format	g_nls_date_format varchar2(4000);
pragma	pragma exception_init (e_package_invalidated, -04068);
raise	raise e_package_invalidated;
end	end if;
end	end ut;

RESET_NLS Procedure

Helper procedure to reset NLS session parameter to it's original state.
It needs to be called after refcursor is open in order restore the original session state and keep the NLS date setting at default.

Syntax

procedure reset_nls

Example

ut_expectation := expect()

[martindsouza]

@lwasylow I'll have to test this to see what's triggering it (won't get to it for a while though).

In the mean time could you use -- for all the comment lines?

-- utPLSQL - Version 3
-- Copyright 2016 - 2017 utPLSQL Project
-- 
-- Licensed under the Apache License, Version 2.0 (the "License"):
-- you may not use this file except in compliance with the License.
-- You may obtain a copy of the License at
-- 
--     http://www.apache.org/licenses/LICENSE-2.0
-- 
-- Unless required by applicable law or agreed to in writing, software
-- distributed under the License is distributed on an "AS IS" BASIS,
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-- See the License for the specific language governing permissions and
-- limitations under the License.

One other thing I'd recommend is moving the documentation into the package body. The reason behind this philosophy is that devs spend most of their time in the body rather than spec. If they have to change files to update documentation they probably wont.

[lwasylow]

Will try that , thanks.