Search Unity

Understanding the documentation

Discussion in 'Documentation' started by Mothil, May 3, 2015.

  1. Mothil

    Mothil

    Joined:
    Jan 14, 2014
    Posts:
    434
    Hello friends, I have a question regarding how to approach the API.
    Now as a newbie there's a lot I don't understand yet, but I'm trying desperately to work on that. It happens very often I have trouble understanding what things do in the documentation, even though it should all be there.

    Let's take for example OverlapCircle (http://docs.unity3d.com/ScriptReference/Physics2D.OverlapCircle.html). There's a long line there:
    Code (CSharp):
    1. public static Collider2D OverlapCircle(Vector2 point, float radius, int layerMask = DefaultRaycastLayers, float minDepth = -Mathf.Infinity, float maxDepth = Mathf.Infinity);
    And a lot of parameters, but not how to use it. There are no examples, which bugs me a little bit, but I guess it's my own fault for rushing into it.

    What would you say is the correct way to approach being able to read and understand the API? I assume the more logically-minded people than me can just sit down and read it and learn from there, but I learn a lot faster with examples. It frustrates me a little that I continuously have to search google for answers, when I should be perfectly capable of fixing it with the documentation by my side.
     
  2. andeeeee

    andeeeee

    Joined:
    Jul 19, 2005
    Posts:
    8,768
    We are definitely believers in having good code samples for the API but I would agree that we still have quite some work to do. The way we are approaching this task is to use page view statistics to get an idea of which script ref pages are considered most "important" and then use this information to guide our improvements. (Of course, this isn't 100% of the story because the number of hits a page gets doesn't always mean it is important or has room for improvement.)

    I'm not sure where Physics2D.OverlapCircle comes in terms of priority just now but it is indeed a good example of an API function that needs some good sample code. As well as working through the samples ourselves, we are also planning a new and improved version of the suggestion system that we trialled briefly last year. This should give us another source of information about which API pages are important and, naturally, we will welcome code sample submissions from users too! :)
     
    Mothil likes this.
  3. jwinn

    jwinn

    Joined:
    Sep 1, 2012
    Posts:
    72
    Hey Andeeeee— what's the best way to send code sample submissions? Also, have you folks considered adding in something like a "Suggest Improvement" button to docs pages that allows users to help out? This might alleviate some of the burden.
     
  4. andeeeee

    andeeeee

    Joined:
    Jul 19, 2005
    Posts:
    8,768
    @jwinn: you can post code sample submissions to the Documentation section of the forum or use the bug report app (although we prefer the forum if that's OK with you).

    A "Suggest Improvement" button was trialled last year and found to be successful. We are going to reinstate that in the near future but with a few additional features.
     
    jwinn likes this.