Hello people. I came to a point where I wanted to document some of my other assets in progress (see signature) and start working on this tool, but it got evolved a bit further into something I find quite usefull.
Search, Browse Reference any type for it’s fields, properties and methods in a nice and comprehensive way
View and reference your project types in a type based hierarchical view
Read the comments and blocks written for your code’s classes, fields, properties and methods, within DocMe
Open your IDE at the declaration of any listed member if it’s in your project (meaning you have the script)
Read official Unity documentation for Unity types and link to the web documentation
interesting. some questions and remarks:
your example shows unityscript code. is it restrcited to it or does it allow c# and boo too?
for what price will it be available?
is the code included or dll?
when is the parsing-process invoked? when the window is opened or manual? does it only reparse changed stuff?
is the token (fe $C) really required? the correct type should be known through reflection already.
are the source files parsed or the built assembly? the assembly should not contain comments afaik?
can custom documentation also be added via the docme window? possibly even written in the sourcefile?
this would be “necessary” for me to buy your package.
and i’m a bit concerned about the unityscript style.
Hey Thats all great questions that will help other people understand what this is as well. So here we go:
It’s just an example It works with all languages since it’s pure reflection
The source code is totaly included
Parsing for documentation meaning remarks/comments and fetching from the web (for Unity types) is done automaticaly when the window opens or on assembly reload and the first time of that session that a Type is selected to be viewed. Then it’s cached until window reopens
Those tokens are only for when you want to add remarks to be readen in DocMe and for your own code. Nothing more A field, property or method member will show in DocMe regadless of those tokens, though without remarks
“Eat” has tokened remarks, while “Drink” does not but of course it’s there
The Project View on the right is an added bonus to view your won project code in a Type hierarchical view. Clicking on any of those types will view it just like you would have clicked on a Type say for example of a Method parameter.
Hierarchical Project View
You are viewing the assembly
Any type seen is clickable to be viewed
Unity types show remarks fetched from the official documentation site
Custom types show tokened remarks
and of course the rest dont have remarks
Thats exactly what those tokens are for
That’s already been done for all token remarked members and I will update/submite once the package is accepted.
PS:UnityScript is a great language
I’ve submitted DocMe for 40$ / 30Euro. I believe it’s a fair price
thats clear to me. my question refered to the specific token for each “type” (ie C for class, methods, P for properties). i assume there could be a general token for docme and the assignment to the specific type (class, property) can be done automatically. i’m afraid i use the wrong token for example variable vs member vs field and function vs member.
thats where i’m confused. you parse the assembly but afaik the cil code should not contain any comments (tokens) any more. thats why i ask if my understanding is wrong and how you do it in the package.
i meant it the other way round and asked if i can enter description etc in the docme window itself. and if it is then put into the code at the right position. but i guess that would cause some trouble and when you use the assembly and not the code files itself its even more unlikely.
i disagree ;). btw in what language is docme written?
its acceptable for me. but if the code is in unityscript thats a nogo for me. sorry. i don’t allow US in my project. and i don’t feel like porting a whole package.
Thanks to your feedback, I’ve improved the source code parsing and now indeed you only need one token"$"
Further there is the ability to go to the definition of any member listed regardless if it has remarks
The whole editor works mainly with Types. but when a type exists in the project it is retrieved by seaching the Monoscripts existant at the start, at which point those project types are also “linked” together to create the hierarchical view at the right. So at any point it is known if a type is of project or not and at which monoscript is defined and thus the comments parsing is done from it, but other than that it’s just types. After parsing, the comments are stored and shown in the editor when they need to.
Since I have reference to the souce (which is parsed for comments), that maybe could be done, although I wouldn’t like to mess with your code
Anyway though, I haven’t though of it. Maybe it could be done at some point.
unityscript
That’s fair enough, typicaly what I do but in reverse except some rare cases where I must have c# heh
Moreover I’ve added a Type search at the top. I think I should update the original post now
its still tempting as i find your package quite convenient and what i’m looking for. do you have the possibility to compile the code into a dll? if that is not possible its another thing to add to the us-disadvantage list ;).
the main reason why i avoid us is the incompatibility between c# and us. i know it “should” work when taken appropriate steps like putting it into special folders but i don’t consider this compatibility its more like a “dirty” workaround.
i’m interested if and how you support enums. are the single values displayed? can the attributes be made visible?
anyway, i’m happy that i could give you some remarks and they helped you to improve the product.
EDIT:
how do you handle extension methods? could you please show an example how it looks? are they put to the type they are made for or do they reside in the class they are defined in?
how do you handle hyperlinks encountered in comments? i often have links to remind me where i have “borrowed” the code from or to explain certain aspects. it would be great if a click in the docme window on a link-comment would also open the site directly.
Thanks
Unfortunately Uscirpt can’t be compiled as far as I know. I will agree that’s a disadvantage
By the way there is no need to put it in any special folder. I haven’t put it in such a folder and can view c# scripts just fine. Just saying
Here we go with screens:
You can view an enum fine, and its values under ‘fields’
Extension Methods do of course show into the declared type as normal, but they also do show up into the type they are made for
If the extension method has comments you can read them as normal even if not viewing the type they are declared like here.
Also clicking the “S” will open the script at the declaration line in the script they are defined if any.
Byt the way, since we are viewing a Unity Type, we also read documentation taken from the web and clicking the “?” (changed from “@”) will open the browser to the official doc for the member.
Like extensions there are more info that are shown like so:
Finaly yes, you can toggle on and off showing attributes
I don’t handle hyperlinks in the comments yet, but sure, I will add it to the ToDo list.
well, your package seems quite advanced so i will give it a try once its available regardless of the language.
if you think about a c# port somewhen (maybe others also request it) there is a free converter available and an advanced one in the store (linked at above site). so you could at least automate the process.
if you have access to visual studio (pro) there is a plugin available which enables unityscript to be used in vs. maybe it can also compile then. when you have a dll it can be reflected to gain valid c# code.
just for your consideration. i purchase it anyway but a c# port would come in handy for me ;).
just drop a line here once it accepted and available in the store.
Why require tokens at all and not just parse all comments?
You don’t need that plugin to get a dll since Unity compiles your Java-/UnityScript or you into a dll. And trying to get valid C# code from a Java-/UnityScript assembly/dll file isn’t that easy since the IL generated is not C# friendly (ie the code will have some weird stuff).
i guess to avoid the documentation to become too verbose. having any comment in the documentation just clutters it. and how do you assign a comment to a class/method/field/property properly? so this solution is convenient and allows enough control.
it compiles several dll’s without much controll on where to put what and with everything included. some (editor)scripts maybe also spread above several dll’s when in different folders. but for a clean project with nothing else this should be sufficient. i don’t know if the editor folder is also compiled as it is not available in the built but nuverian stated the code is not in special folders.
thats interesting as i have read this method for the purpose of “easy” converting us to c# and i thought the generated c# code should at least be valid. but yeah it makes sense that the generated il code is different since it is compiled with its own compiler. unfortunately i don’t find the link any more where i read this.
I might do a port to c# in the future if there is much demand for it
I’ve added an option to parse all comments found above a declaration
The reason was because I started with such a logic plus for clarity as Exiguous stated, but parsing improved thanks to feedback, so it’s doable
I’ve made an update to the DocMe comments parser and as a result your usual
comment blocks will be displayed within DocMe.
Following is a screenshot of an NGUI class as is, in DocMe. And of course you can open your IDE as usual at the declaration line of any member by clicking that small “S” button on the left of the entry.
Hello zipper.
I really can’t understand why you were disapointed. I mean, it’s an editor script. You don’t even have to move it is special folders or anything. It will just work as it is. Now I’m not trying to convice you or anything. I just don’t understand the real reason, which I would like to learn
With that being said, Im elaborating on providing a DLL
i can’t speak for zipper but maybe you are also interested in my reasons for disliking unityscript.
this blog (i have linked already) shows some things you are missing in unityscript. so you are effectively crippled.
i have read about “incompatibility” to c# way too often. it may not be the case with your product (editor script) but this issue still leaves a bad feeling.
i’m not comfortable with the syntax. so when i want to lok up something or even change something in your code i will hate it.
unityscript is very implicit and does many things hidden and without programmers consent and knowledge.
some examples:
when i stareted with unity i also choosed unityscript as my language albeit i came from c++ and have worked in c# with xna before. one day i had a bug where the behavior was unexpected and i could not find out what was wrong for several days (lost of my lifetime). then i found out that i had mistyped a variable and US simply defined a new one for me, silently and dastardly. this was before pragma strict had been included in all scripts. but now i still find it very odd. in c# i explicitely declare a variable, simple. in US i must tell the compiler to NOT implicitely declare variables when i want to keep my sanity. odd and unlogical.
in US every script automatically inherits from monobehavior. i don’t know how to prevent this. i need many classes which does not do this.
in US you can write transform.position.x = 5 in C# you must assign a new vector because its a property. so it may be shorter and a little more convenient but this hides what really happens. and when stuff is hidden its potential source of bugs. i prefer an explicit language where i must tell everything i need and not let the compiler decide how to handle things without my knowledge. in the end the compiler is your strongest debugging tool you have at hand and when he does not care when you do crap and silently makes it fit you loose its capabilities to a big extent.
so my antipathy towards US does not come from opinion but from experience and when i can have a better language why should i mess with the worse one?
also when you read through the forums you may recognize that most long term unity users use c# and US is mainly used by “noobs” you hear nothing again from and only very few professional people. so this preference also gives a clear sign.
this is only a half step as many people (including me) also avoid assets with code in dll’s as you can’t extend/adapt it. this is especially annoying when the author vanishes and does not provide further support. so if you want to increase your sales i would definetly not hurt to provide a c# version. i don’t know if its only zipper and me who are interested but i think that more people in the future would be interested when it would be in c#. when you look thorugh the asset store you may notice that most assets have c# scripts so its the quasi standard and when you ignore it you only hurt your sales.
Look, I don’t disagree that c# is better, but you seem to asume that if I’m a bad driver and I get a McLaren I suddently become Shumacher :). What I mean is that ‘tools dont make the craft’.
But anyway, I wouldn’t like to argue about language preferance.
Regardless and with the argument out of the way, DocMe is now available in C# :). It has just been approved.
It works with all languages since it’s pure reflection
