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.
Related
The two functions mkYesodData and mkYesodDispatch in the Yesod framework are supposed to separate the handler definition and the dispatch process. Though by some miracle (to me), templates use this interesting function "resourcesApp":
mkYesodDispatch "App" resourcesApp
The only mention of this function I have found in hoogle is in the Hledger package. And it is not a yesod dependency.
In the school of Haskell by this link they give an explanation that resourcesApp is "generated" by mkYesodData, although it still does not work for my side.
https://www.schoolofhaskell.com/school/advanced-haskell/building-a-file-hosting-service-in-yesod/part%202
What is the reason for this?
There's some Template Haskell (TH) going on under the hood in Yesod, and I think this is what's confusing you. Template Haskell can be confusing when searching in documentation because it produces values at compile-time for use at runtime that aren't there before the code is compiled. resourcesApp is just one of these values.
In the code you reference, the author describes that you must have another module (which he calls Foundation) in which you have invoked mkYesodData. Indeed, without this other module, the code in the Dispatch module won't work. Strangely, it's not until (Part 4)[https://www.schoolofhaskell.com/school/advanced-haskell/building-a-file-hosting-service-in-yesod/part%204] that he seems to define the Foundation module, but you can see that there is a line:
mkYesodData "App" $(parseRoutesFile "config/routes")
That may not look like it defines a value called resourcesApp, but sure enough, it does.
In short, you should be able to get your code working by just finishing the entire tutorial and running the code altogether.
In case you're wondeering, a call to mkYesodData takes a String and then literally generates code that defines a value names resources**** where the **** is the string you passed. In this case, that would be a value resourcesApp, but in someone else's Yesod project, it could be resourcesFoo. Furthermore, since this resourcesFoo value isn't concretely in the code, projects that use Yesod typically wouldn't have it show up in their export lists or haddock documentation. It's actually very strange that you found even one hit for resourcesApp on hoogle at all, but upon closer examination, it kind of makes sense: Hledger seems to be some sort of extended interface around yesod, so they pre-generated the TH values so that they would be easily accessible to users.
As another note, TH has some restrictions in its use. For one, you typically need to perform the TH invocations ("splices" as they're typically called) in a separate module than the one you use the generated values. This is probably why the author has you create a separate Foundation module rather than just putting the line mkYesodData ... in the Dispatch module.
Im trying to accomplish a twincat 3 library which does things using global constants defined in the main project, like creating arrays the size of those constants and cycling trough them. However I've been unsuccessful and I wonder if this can be done. I just get this error "Error 4 Border 'cPassedConstant' of array is no constant value" when I try to build the main project. The error comes from the array defined in the library.
I've tried making a GVL with a constant of the same name to the library and then setting the "external implementation" property true but that does not help.
My goal here is to make a IO management library with filtering and such. And then I could just add it to the main project and define some constants like "cDigitalIputsCount","cAnalogInputCount" and so on.
Maybe you can get along with the new ARRAY[*] feature instead, although it is still very limited. There is no other way than to define the constant in the library.
The library concept is the same as in other environments. A library provides you reusable components. Your main project depends on the library and not the other way around. Therefore your library cannot know a thing about the project where it is used.
A confusing thing in TwinCat3 is, that you can build projects successful with programming errors inside. The TwinCat3 compiler allows broken code inside a project as long as it is not called. Therefore when you ship libraries you should always use "Check all objects".
You should check Beckhoff's feature called Parameter List. By adding a parameter list to the library project, you can re-define library constants in the project that uses the library. The definition happens in the library manager.
Image from Beckhoff's site:
I think that should do it. Of course, the other option is to use the ARRAY[*] option, which is awesome too (for a PLC programming world). The problem with parameter lists is that it is a project-wide re-definition. Using the ARRAY[*] allows the size be changed dynamically.
I would suggest using a variable length ARRAY[*], as explained in the link below (and also in the Beckhoff/Infosys, section DataTypes/Array).
The point is that you should declare the ARRAY[1..cAINs] of FB_AnalogIO in your main program (it knows the FB_AnalogIO from your analog library and can declare it with a constant size).
The PRG_IO should then be changed to either a function or function block, so that it accepts the ARRAY[*] as a VAR_IN_OUT without knowing the exact size.
https://stefanhenneken.wordpress.com/2016/09/27/iec-61131-3-arrays-with-variable-length/
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 am very new to mib2c, and I need to list all attributes which belong to one variable.
I work with mib2c tool from NET-SNMP and there are configuration templates for generating the code.
There are variables with many attributes, look like:
$var.defval
$var.type
I would like to see all these attributes, in order to use them in the generated code.
I know, for mib2c attributes there is man page, but there is not everything. (For example I know the attribute $var.needlength exists, and it is not mentioned in that man page).
I don't know how the $var is defined and fulfilled.
How can I list all attributes of $var?
I'm not sure how you can do this programmatically, given the constraints of the mib2c pseudo-Perl but I just looked in /usr/bin/mib2c (it's a script, not a compiled executable so you can easily examine the code) and found the following.
There are only four undocumented variables in the mib2c script:
lastchange
storagetype
needlength
enumrange
There are many more documented variables in the mib2c script:
uc
objectID
commaoid
oidlength
subid
module
parent
isscalar
iscolumn
children
perltype
type
decl
readable
settable
creatable
noaccess
accessible
rowstatus
hasdefval
defval
hashint
hint
ranges
enums
access
status
syntax
reference
description
That being said, I'm not sure what exactly you are hoping to find, so I'm not sure that this really answers your question.
With Java on one side and Ruby/Groovy on the other, I know that in the second camp I'm free to make typos which will not get caught until run-time. Is this true of all dynamically-typed languages?
Edit: I've been asked to elaborate on the type of typo. In Ruby and in Groovy, you can assign to a variable with an accidental name that is never read. You can call methods that don't exist (obviously your tests should catch this, it's been said). You can refer to classes that don't exist, etc. etc. Basically any valid syntax, even with typographical errors, is valid in both Ruby and Groovy.
In Perl, if you declare use strict in your code, then you must declare your variables with my. Typos in variable names will then be caught at compile-time. This is one of the biggest things I miss when coding in Python.
Python is typo-friendly in the way you described in your question.
But this does not mean that these 'typos' can only be caught # runtime.
When using a code analyzer like pylint (ideally integrated into your development environment) you'll catch 'most' of these consistently before hitting 'run'.
For the most part, yes. Dynamic typing and not requiring declaration of variables are language properties that are frequently found together.
However, these are not inherently related. A language can easily have dynamic typing while requiring variable names to be declared before use. As ire_and_curses mentions, this can be achieved in Perl via the "use strict" directive.
Here's what happens when I try to get into the pitfalls you mentioned in Squeak and Dolphin, two implementations of the dynamic language Smalltalk 80.
You can assign to a variable with an accidental name that is never read
The Smalltalk language requires temp and instance variables to be declared. If I try to compile a method containing an undefined variable I get a compile-time error.
| anArray |
anArrray := Array with: 2 with: 1. "Unknown variable anArrray"
Creating variables dynamically is not something dynamic languages have to allow. There's a difference between typeless declarations and no declaration at all.
You can call methods that don't exist
The compiler issue a warning if you use a selector (i.e. method name) that is entirely unknown.
The compiler won't bother if I call the method paint on an array because there's another class in the system implementing paint. That error will only be caught at runtime.
If however I call the method sortt (while I intend to call sort) the compiler generates a warning. When developing top-down you can proceed pass these warnings.
| anArray |
anArray := Array with: 2 with: 1.
anArray paint. "Runtime error. You can't paint an array but perhaps a Shape"
anArray sortt. "Compile-time warning"
You can refer to classes that don't
exist
This is not allowed. Though in Squeak you can quickly create a new class from the error dialog if needed.