Search Unity

  1. Are you interested in providing feedback directly to Unity teams? Sign up to become a member of Unity Pulse, our new product feedback and research community.
    Dismiss Notice

DocMe - Reflection Code Reference | Project Documentation Tool [RELEASED]

Discussion in 'Assets and Asset Store' started by nuverian, Jan 15, 2014.

  1. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Now in C#

    $main.png

    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 <summary> 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

    $extraWindow.png

    All the comments and summary blocks written for a class, field, property or method declaration are shown within DocMe to read!

    Here is an NGUI class for example $ngui.png

    [video=youtube_share;36nd5cuosRI]http://youtu.be/36nd5cuosRI​





    The source code is included
    Works with C#, US, Boo*

    (*Comment parsing for Boo is not yet supported)

    Roadmap
    *Export project based code to htlm documentation
    *Hyperlinks in comments
    *Your Suggestions
     
    Last edited: Feb 24, 2014
  2. exiguous

    exiguous

    Joined:
    Nov 21, 2010
    Posts:
    1,520
    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.
     
  3. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    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

    $2014-01-17_00h58_43.png
    "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.

    $info3.png
    Hierarchical Project View

    $2014-01-17_02h17_49.png
    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.

    $2014-01-17_01h59_45.png
    PS:UnityScript is a great language :)


    I've submitted DocMe for 40$ / 30Euro. I believe it's a fair price :)

    Thanks for all those question!
     
    Last edited: Jan 17, 2014
  4. exiguous

    exiguous

    Joined:
    Nov 21, 2010
    Posts:
    1,520
    thanks for the reply nuverian,
    you are welcome. here are more ;).

    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.
     
  5. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    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 :p
    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

    $2014-01-18_20h14_12.png
     
    Last edited: Jan 18, 2014
  6. exiguous

    exiguous

    Joined:
    Nov 21, 2010
    Posts:
    1,520
    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.
     
    Last edited: Jan 19, 2014
  7. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    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'
    $enum.png


    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
    $extension.png

    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:

    $implemented.png

    $override.png

    Finaly yes, you can toggle on and off showing attributes
    $2014-01-19_19h16_16.png


    I don't handle hyperlinks in the comments yet, but sure, I will add it to the ToDo list. :)
     
    Last edited: Jan 19, 2014
  8. exiguous

    exiguous

    Joined:
    Nov 21, 2010
    Posts:
    1,520
    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.
     
  9. Brainswitch

    Brainswitch

    Joined:
    Apr 24, 2013
    Posts:
    270
    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).
     
  10. exiguous

    exiguous

    Joined:
    Nov 21, 2010
    Posts:
    1,520
    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.
     
  11. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    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
     
    Last edited: Jan 19, 2014
  12. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    DocMe is now live on the Asset Store :)
    Here
     
  13. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Here is a video for kind of a walkthrough of using DocMe, since videos are always better than screens :)

    [video=youtube_share;36nd5cuosRI]http://youtu.be/36nd5cuosRI​
     
  14. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    I've made an update to the DocMe comments parser and as a result your usual <summary> 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.

    $ngui.png

    Will let you know as soon as it goes live
     
  15. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Alright. Version 1.2.5 is now up :)
     
  16. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Im very happy to see that the Asset Store team featured DocMe in the Editor Extensions Category. Thank you :)
     
  17. zipper

    zipper

    Joined:
    Jun 12, 2011
    Posts:
    89
    Was disappointed to see this is Unity Script.
    As a rule -> i don't purchase Unity Script plugins.
    I was all ready to buy :(

    I would buy a C# version right now.
     
  18. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    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
     
  19. exiguous

    exiguous

    Joined:
    Nov 21, 2010
    Posts:
    1,520
    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.
     
  20. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Hey exiguous,

    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.

    Best regards,
    Gavalakis
     
  21. exiguous

    exiguous

    Joined:
    Nov 21, 2010
    Posts:
    1,520
    as bad driver in a McLaren you have still better chances than a bad driver in a Fiat Panda. you will not win the race but maybe you are not the last one ;).

    i think many people will disagree here. just imagine you had to develop Call of Duty in Assembler. the tools are very important for productivity and qualitity, especially in software development.

    your preference can stay the same. my point was that when you want to sell your package your customers are mostly c# devs and some/most/few? of them don't want US code for several reasons. so you effectively reduce your customer range by ignoring their requirements/desires and their language preference. so you are hurting YOUR sales by doing so. so when you want to reach many people and be competitive you have to ignore your own preference from time to time and adapt to the preference of others. thats all i wanted to say.

    well, thats good news. i honour this by purchasing ;).
     
  22. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Yeah, I know what you ment and you have your points there, not worries.
    Thanks. I hope you enjoy and find it useful as much as I do :)
     
  23. Jimww

    Jimww

    Joined:
    May 14, 2013
    Posts:
    63
    Hi, I just bought this but it seems that the docs being pulled in from the Unity site are including some HTML as well as wrong data, it seems the item descriptions within are wrong as well. They must have changed their site? Clicking the "?" does point to the right doc location on the web though. OS X Unity5 non-pro
     
  24. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Hello,
    I am sorry for this late reply, but I honestly missed your post completely :/
    Thanks for noting the issue. I will fix the documentation parsing very soon.
    Meanwhile I will also improve on the non-pro white theme so that it can actually be readable.
    Please expect an update within a week more or less.

    Thanks a lot.
     
  25. gamescorpion

    gamescorpion

    Joined:
    Feb 15, 2014
    Posts:
    131
    Hey there, @nuverian: I just purchased this, but I need a Unity 4 version. Do you have an older package?

    Pls PM me.

    Thanks,

    Nav
     
  26. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Hello and thanks!
    If you import DocMe in Unity 4 it will work fine. I just re-chcked it with Unity 4.6 now.
    Have you tried this?

    Thanks
     
  27. gamescorpion

    gamescorpion

    Joined:
    Feb 15, 2014
    Posts:
    131
    Hi there,

    Yes I tried it and it said that this package is not compatible with your version of unity (4.6.3p4). I tried both methods (Download and Import, then directly inside of unity importing a custom package. Both failed).

    Thanks,

    Nav
     
  28. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Hello and sorry for late reply.
    I tried sending you a PM, but it's seems you've disabled receiving PMs.

    Let me know when you enable.
    Thanks.
     
  29. Sylafrs

    Sylafrs

    Joined:
    Jun 25, 2013
    Posts:
    34
    Hello,

    So far, this package is awesome :)
    I just have an issue : I have to close/open the window each time I compile the project.

    Is there a way to make the window refresh itself when the project finishes to compile ?

    Thank you :)
     
  30. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Hey,

    Thanks a lot! I am glad you like it :)
    I will make an update to the package to handle recompiling.
    Expect it very soon.

    Thanks again.
     
    antoripa likes this.
  31. antoripa

    antoripa

    Joined:
    Oct 19, 2015
    Posts:
    1,163
    Hi,
    excellent asset. I bought and it is what I need.
    Is there any plan to add export features to create HTML Doc ?
     
  32. nuverian

    nuverian

    Joined:
    Oct 3, 2011
    Posts:
    2,074
    Hey,
    Thanks a lot. I am really glad you like DocMe :)
    There was a plan for that once, but the idea was dropped due to the other projects requiring a lot of attention. Sorry.
    By the way, your Sentieri asset WIP look super great and something we can definitely use in our current project. Looking forward to see it finished ;)
     
    antoripa likes this.
  33. antoripa

    antoripa

    Joined:
    Oct 19, 2015
    Posts:
    1,163
    Hi @nuverian ,
    thanks for your prompt reply .. maybe I will try to put something on top of your asset to create HTML ...
    and thanks for Sentieri ... if you could share your needs, it will help me to check a "real world" scenario ... I can even send you a beta as soon as UI is ready .. just send me a PM ...
    Cheers,
     
  34. Binex_Solutions

    Binex_Solutions

    Joined:
    Apr 17, 2018
    Posts:
    2
    Seriously a great tool to use specially when you are involved with huge code bases. Oh! by the way we have created a great documentation tool. The main focus of the tool is to generate manuals for different modules along with source documentation using old school XML in HTML. It's blazing fast and easy to use. You can find details on this forum post

    https://forum.unity.com/threads/bmg-easy-to-use-tool-for-quick-manual-faq-generation.532897/

    Note! We are currently running in BETA version and we are willing to provide it for free on request to the individual interested in testing this tool out.
     
  35. dozhwal

    dozhwal

    Joined:
    Aug 21, 2014
    Posts:
    59
    i would be very interessted by HTML doc generator too ! :)
    Navigate in docme is not very fast, and i'd like to export it for external developpers
     
  36. Bezoro

    Bezoro

    Joined:
    Mar 16, 2015
    Posts:
    67
    Just wanted to let you know that DocMe is leaving multiple _DocMeRoutiners cluttering the scene view as you open and close the project.
    I assume that they are supposed to not hang around and get deleted automatically.
    Also maybe they should be marked as HideAndDontSave?

    Unity: 2020.3.0f1
    DocMe: 1.3.6
     
unityunity