I tried to google for it, but couldn't find anything on why Google Closure Compiler and YUI Compressor using different annotations format
Google Closure Compiler is using JSDoc format in which annotations starts with /**
Any annotations in different format are removed.
YUI Compressor only keep annotation if they are started with /*!
I've noticed that most libraries(e.g. jQuery) using /*!
Could you tell me why most libraries use /*! and not JSDoc(which I guess quite popular?) format?
I couldn't find any flags for Google Closure Compiler to keep annotations starting with /*!
What's the best way to parse files with annotations in both formats with Google Closure Compiler and keep all the annotations? Shell script which using stream editor to replace /*! with /** and back again after minification?
Many Thanks!
Closure Compiler removes all comments except those part of #license or #preserve in JSDoc annotations (which it moves to the head of the file). "/*!" serves a similar purpose.
More specifically, no one has care enough to about "/*!" to do the work add support to Closure Compiler. It should be reasonable to do so as both YUI and Closure Compiler use Rhino's javascript parser (I'm not sure what version YUI uses but Closure Compiler uses the current one).
Related
I'm currently going through my project in Jetbrains Pycharm 2017.1.5, documenting all my python 3.6 classes and methods, and several things stand out to me about the docstring format.
I want to link to other methods / functions / classes from some of the docstrings, but I cannot figure out how to do this. The documentation for restructuredText is very, very extensive, but it doesn't say anything about referencing other docstrings with Pycharm. In fact, the vast majority of the snippets from that page do not even work in Pycharm. (Why is that?)
I've managed to find that you can use :class:`<class_name>` to reference a class, but :class:`<class.method>`does not work, and similarly named constructs like :func:`<func_name>` do not create a hyperlink. I've also seen :ref:`<name>` come up, but that one doesn't work either.
(I would switch to Epytext (it has everything I want, plus it's much simpler) in a heartbeat if not for this error: You need configured Python 2 SDK to render Epydoc docstrings in the Ctrl + Q frame.)
It would also be extremely helpful if there was a way to inherit the docstring in subclasses / overridden methods. Pycharm does this automatically if you leave the docstring blank, which makes me think it is possible to do it manually. But, again, I can't find any information on it.
It's turning out to be mind-blowingly complicated to do something so, so simple. So, any help will be appreciated!
I want to link to other methods / functions / classes from some of the docstrings, but I cannot figure out how to do this.
You're correct that the reStructuredText documentation does not cover this, because it's not a feature of reStructuredText.
Likely you are (explicitly, or implicitly via some tool) using the Sphinx system – a superset of Docutils – to allow (among many other features) references between different docstrings.
Sphinx defines several Docstring “roles” (the :foo: before the backtick-quoted text) for different purposes:
doc, a reference to an entire document.
ref, an arbitrary cross-reference.
… many others.
For specifically Python code, the “domain” py has its own specific set of roles for Python code docstrings:
:py:mod:
Reference a module; a dotted name may be used. This should also be used for package names.
:py:func:
Reference a Python function; dotted names may be used. The role text needs not include trailing parentheses to enhance readability; they will be added automatically by Sphinx if the add_function_parentheses config value is True (the default).
:py:data:
Reference a module-level variable.
:py:const:
Reference a “defined” constant. This may be a Python variable that is not intended to be changed.
:py:class:
Reference a class; a dotted name may be used.
:py:meth:
Reference a method of an object. The role text can include the type name and the method name; if it occurs within the description of a type, the type name can be omitted. A dotted name may be used.
:py:attr:
Reference a data attribute of an object.
:py:exc:
Reference an exception. A dotted name may be used.
:py:obj:
Reference an object of unspecified type.
Is it possible to get a list of all the arguments a constructor takes?
With the names and types of the parameters?
I want to automatically check the values of a JSON are good to use for building their equivalent as a class instance.
Preferably without macros... I have build a few, but I still find them quiet confusing.
Must work with neko and JS, if that maters.
Thanks.
I think you want to look at Runtime Type Information (rtti)
From the Haxe Manual: The Haxe compiler generates runtime type information (RTTI) for classes that are annotated or extend classes that are annotated with the #:rtti metadata. This information is stored as a XML string in a static field __rtti and can be processed through haxe.rtti.XmlParser. The resulting structure is described in RTTI structure.
Alternative; If you want to go with macros, this might be a good start
http://code.haxe.org/category/macros/add-parameters-as-fields.html
I've been tasked with creating conformance tests of user input, the task if fairly tricky and we need very high levels of reliability. The server runs on PHP, the client runs on JS, and I thought Haxe might reduce duplicative work.
However, I'm having trouble with deadcode removal. Since I am just creating helper functions (utilObject.isMeaningOfLife(42)) I don't have a main program that calls each one. I tried adding #:keep: to a utility class, but it was cut out anyway.
I tried to specify that utility class through the -main switch, but I had to add a dummy main() method and this doesn't scale beyond that single class.
You can force the inclusion of all the files defined in a given package and its sub packages to be included in the build using a compiler argument.
haxe --macro include('my.package') ..etc
This is a shortcut to the macro.Compiler.include function.
As you can see the signature of this function allows you to do it recursive and also exclude packages.
static include (pack:String, rec:Bool = true, ?ignore:Array<String>, ?classPaths:Array<String>):Void
I think you don't have to use #:keep in that case for each library class.
I'm not sure if this is what you are looking for, I hope it helps.
Otherwise this could be helpful checks:
Is it bad that the code is cut away if you don't use it?
It could also be the case some code is inlined in the final output?
Compile your code using the compiler flag -dce std as mentioned in comments.
If you use the static analyzer, don't use it.
Add #:keep and reference the class+function somewhere.
Otherwise provide minimal setup if you can reproduce.
I know that since Groovy 2.0 there are annotations for static compilation.
However it's ease to omit such annotation by accident and still run into troubles.
Is there any way to achieve the opposite compiler behaviour, like compile static all project files by default and compile dynamic only files chosen by purpose with some kind #CompileDynamic annotation for example?
I have found some (I believe recently introduced) feature which allows doing so with Gradle.
In build.gradle file for the project containing groovy sources we need to add following lines:
compileGroovy {
configure(groovyOptions) {
configurationScript = file("$rootDir/config/groovy/compiler-config.groovy")
}
}
or compileTestGroovy { ... for applying the same to test sources. Keep in mind that neither static compilation nor type checking works well with Spock Framework though. Spock by its nature utilizes dynamic 'groovyness' a lot.
Then on a root of the project create folder config/groovy/ and a file named compiler-config.groovy within. The content of the file is as follows:
import groovy.transform.CompileStatic
withConfig(configuration) {
ast(CompileStatic)
}
Obviously path and name of the configurationScript may vary and it's up to you. It shouldn't rather go to the same src/main/groovy though as it would be mixing totally separate concerns.
The same may be done with groovy.transform.TypeChecked or any other annotation, of course.
To reverse applied behaviour on certain classes or methods then #CompileDynamic annotation or #TypeChecked(TypeCheckingMode.SKIP) respectively may be used.
I'm not sure how to achieve the same when no Gradle is in use as build tool. I may update this answer in the future with such info though.
Not at this time, but there is an open Jira issue here you can follow to watch progress for this feature
There was also a discussion about methods for doing this on the Groovy developers list
I remember from my Perl days the "use strict" statement that cause the runtime to do extra validations. Is there an equivalent for Groovy?
I do not enjoy being bitten during runtime by what can be detected on compilation, like passing too few arguments to a constructor.
Groovy 2.0 now has optional static type checking. If you place a #groovy.transform.TypeChecked annotation on a class or method, groovy will use strict, Java-like static typing rules.
In addition, there's another annotation #groovy.transform.CompileStatic that is similar, except it goes a step further and actually compiles it without dynamic typing. The byte code generated for these classes or methods will be very similar to straight Java.
These annotations can be applied to an individual class or method:
import groovy.transform.TypeChecked
#TypeChecked
class MyClass {
...
}
You can also apply them globally to an entire project without adding annotations to the source files with a compiler config script. The config script should look something like this:
withConfig(configuration) {
ast(groovy.transform.TypeChecked)
}
Run groovy or groovyc with the -configscript command line option:
groovyc -configscript config.groovy MyClass.groovy
There's more information in the Groovy manual:
http://groovy-lang.org/semantics.html#static-type-checking
http://groovy-lang.org/semantics.html#_static_compilation
Is there an equivalent for Groovy?
Not that I know of.
I do not enjoy being bitten during
runtime by what can be detected on
compilation, like passing too few
arguments to a constructor.
Then Groovy is probably the wrong language for you and you should use something like Java or C# instead. Alternatively, there is a version of Groovy, known as Groovy++ which has much stronger type-checking, but I don't consider it sufficiently mature for production use.
IntelliJ (and possibly other IDEs) provides a lot of warnings about dodgy Groovy code. Although these warnings don't prevent compilation, they almost give you the best of both worlds, i.e. the safety of a static language and the flexibility of a dynamic language
No, there is no such thing, and there can't be. Perl's "use strict" only prevents the use of undeclared variables (and some very Perl-specific things that I don't think have equivalents in Groovy).
In dynamic languages like Groovy, "passing too few arguments to a constructor" is fundamentally not something the compiler can detect, because class definitions can be changed at runtime via metaprogramming. Also, you usually don't have the type information necessary to know what class to look at.
If you want maximum compile-time checks, use a statically typed language with no metaprogramming, i.e. Java.