subtle error with beginDocumentation()

[jakobkroeker]

Hello,

consider a package with code behind 'beginDocumentation()':

if the package is installed by hand or loaded in its directory everything is fine,

but after 'installingPackage' and a Macaulay2 restart, M2 does not recognize functions placed below 'beginDocumentation'. Even if it is mentioned in the Macaulay2 documentation,
-this mistake is unfortunately not detected during installation process.
-prevents the programmer to place documentation near to the code it documents.

Question,
can this mistake at least be detected automatically,
or is it possible to allow code behind 'beginDocumentation'?

[DanGrayson]

That's a very good point. To fix it, it seems to me we need a system where
the documentation is contained in comments, and is extracted by some
automatic procedure. But writing that would be a pain.

Computers are getting faster, so why not just not use "beginDocumentation"?

On Sun, Mar 24, 2013 at 3:49 PM, jakobkroeker notifications@github.comwrote:

Hello,

consider a package with code behind 'beginDocumentation()':

if the package is installed by hand or loaded in its directory everything
is fine,

but after 'installingPackage' and a Macaulay2 restart, M2 does not
recognize functions placed below 'beginDocumentation'. Even if it is
mentioned in the Macaulay2 documentation,
-this mistake is unfortunately not detected during installation process.
-prevents the programmer to place documentation near to the code it
documents.

Question,
can this mistake at least be detected automatically,
or is it possible to allow code behind 'beginDocumentation'?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/12
.

[jakobkroeker]

Thanks!

If I understand it correctly, to replace 'beginDocumentation()'
without triggering the subtle issue above I have to load "SimpleDoc" and "Text" packages

needsPackage "SimpleDoc";
needsPackage "Text";

to use the doc keyword as before.

Could this explicitly be mentioned in the description of 'beginDocumentation' ?

[DanGrayson]

done 3c46824