Author Topic: .NET Documentation questions.  (Read 13163 times)

0 Members and 1 Guest are viewing this topic.

Kerry

  • Mesozoic relic
  • Seagull
  • Posts: 11654
  • class keyThumper<T>:ILazy<T>
Re: .NET Documentation questions.
« Reply #15 on: November 24, 2015, 09:44:19 PM »
Determining or making Table Records.

Invariably there is no advice to make allowance for Records that have been erased.
Typically the advice is to simply check if the Table Has the record and either return the Id of Add a new Record and return it's Id.

This causes havoc if the Record has been erased in the current session.

One way to resolve this is to check  the IsErased property and take action accordingly
example :
Code - C#: [Select]
  1.     ObjectId layerId;
  2.     Database db = HostApplicationServices.WorkingDatabase;
  3.  
  4.     using(Transaction tr = db.TransactionManager.StartTransaction()) {
  5.         LayerTable lt =  (LayerTable)tr.GetObject(db.LayerTableId, OpenMode.ForWrite);
  6.  
  7.         if(lt.Has(layerName)) {
  8.             layerId = lt[layerName];
  9.             if(layerId.IsErased) {
  10.                 LayerTableRecord ltr =  (LayerTableRecord)tr.GetObject(layerId, OpenMode.ForWrite, true);
  11.                 ltr.Erase(false);
  12.             }
  13.         }
  14.         else // create the layer here.
  15.         { // do mojo here
  16.  

I believe this should be documented prominently because it can be a real trap.
kdub, kdub_nz in other timelines.
Perfection is not optional.
Everything will work just as you expect it to, unless your expectations are incorrect.
Discipline: None at all.

Kerry

  • Mesozoic relic
  • Seagull
  • Posts: 11654
  • class keyThumper<T>:ILazy<T>
Re: .NET Documentation questions.
« Reply #16 on: November 24, 2015, 09:45:34 PM »
The number one issue for me would be the lack of xml documentation included with the API's.  It just boggles my mind that 10 years after creation this is still not implemented.

There should at a minimum be a short summary, a description of each parameter and what it does, and a description of each exception that could be thrown.

Yes, It's time the product grew up.
kdub, kdub_nz in other timelines.
Perfection is not optional.
Everything will work just as you expect it to, unless your expectations are incorrect.
Discipline: None at all.

CADbloke

  • Bull Frog
  • Posts: 342
  • Crash Test Dummy
Re: .NET Documentation questions.
« Reply #17 on: November 24, 2015, 11:08:28 PM »
The number one issue for me would be the lack of xml documentation included with the API's.  It just boggles my mind that 10 years after creation this is still not implemented.

There should at a minimum be a short summary, a description of each parameter and what it does, and a description of each exception that could be thrown.
Yeah, this. All those crazy bools that do...do what!?!?! Having the facts in front of me would save me going to the .NET chm file, then off to the ARX chm file because the .NET one had nothing.

Code samples are also handy. It's all well and good to talk about how to use something but I'm sure I am not the only one who sees an actual example and says "oh, that's what they meant there". They are also handy for showing best practices.

Kerry

  • Mesozoic relic
  • Seagull
  • Posts: 11654
  • class keyThumper<T>:ILazy<T>
Re: .NET Documentation questions.
« Reply #18 on: November 24, 2015, 11:39:13 PM »
I'd like to see Hyperlinks working in the CHM Help files.

kdub, kdub_nz in other timelines.
Perfection is not optional.
Everything will work just as you expect it to, unless your expectations are incorrect.
Discipline: None at all.

Kerry

  • Mesozoic relic
  • Seagull
  • Posts: 11654
  • class keyThumper<T>:ILazy<T>
Re: .NET Documentation questions.
« Reply #19 on: November 25, 2015, 12:59:51 AM »
< .. > On the base of first message of this theme I thought the Autodesk has the plans for editing documentation and therefore they want to get the wishes about it.

Essentially, this is correct.

Why don't you try again :)

I think it is better if we deal with one item per post and give as much information as possible to help these guys make any changes.

Regards,
kdub, kdub_nz in other timelines.
Perfection is not optional.
Everything will work just as you expect it to, unless your expectations are incorrect.
Discipline: None at all.

Andrey Bushman

  • Swamp Rat
  • Posts: 864
Re: .NET Documentation questions.
« Reply #20 on: November 25, 2015, 03:32:02 AM »
Why don't you try again :)
Because I am forced to be a realist.

Andrey Bushman

  • Swamp Rat
  • Posts: 864
Re: .NET Documentation questions.
« Reply #21 on: November 25, 2015, 04:46:37 AM »
If Autodesk through Kerry implies the editing of spelling and a punctuation, then I don't see the sense in this theme. I very much doubt that Autodesk is capable to enter to documentation essential editings (except the punctuation) on the basis of programmer's desires.

In my opinion when Kerry or any other customer creates such themes he is to designate the border of sandbox more clearly...
Quote from: Kerry
Be explicit.
No bitching.
Be realistic.
Where a wish stops being "realistic"? In my opinion the volume of work for adding XML comment to API is not less than the work for any my wish which was pointed by me. Then on the basis of what criteria the "reality" or "unreality" is defined? Also, I thought my wishes are explicit and are not bitching...

So, I don't understand Kerry and his request. Therefore I haven't any wish.

Kerry

  • Mesozoic relic
  • Seagull
  • Posts: 11654
  • class keyThumper<T>:ILazy<T>
Re: .NET Documentation questions.
« Reply #22 on: November 25, 2015, 05:58:11 AM »

I'm sorry I can't make myself understood better Andrey.

We are not dealing with wishes. The offer made by Kean was very simple.
If we provide examples of where the documentation is lacking he will pass the information on to the documentations team.
... or more precisely :
Quote
Please send me an email listing the documentation gaps you care about most and I'll pass it on to the person managing the docs.

I took this for a real offer. Rather than just submit a personal list I thought I'd throw the discussion open to people who use the documentation on a daily basis.

The conditions you quote are mine, not Kean's.
From past experience I believe you are a sensible man and I don't think you need worry about your comments being unrealistic.

I'm sorry you won't be participating because I know you have had some targeted questions in the past that weren't easily resolved from the documentation.

 Stay well,
kdub, kdub_nz in other timelines.
Perfection is not optional.
Everything will work just as you expect it to, unless your expectations are incorrect.
Discipline: None at all.

dgorsman

  • Water Moccasin
  • Posts: 2437
Re: .NET Documentation questions.
« Reply #23 on: November 25, 2015, 10:17:45 AM »
Code samples are also handy. It's all well and good to talk about how to use something but I'm sure I am not the only one who sees an actual example and says "oh, that's what they meant there". They are also handy for showing best practices.

I'll have to disagree on that.  Short, concise code samples showing an optional parameter, object, etc. don't necessarily follow best practices such as error handling.  Perhaps a two-pronged approach: short examples local to the object at hand, plus several overall examples, referenced in multiple places, that also demonstrate overall coding techniques?
If you are going to fly by the seat of your pants, expect friction burns.

try {GreatPower;}
   catch (notResponsible)
      {NextTime(PlanAhead);}
   finally
      {MasterBasics;}

Kerry

  • Mesozoic relic
  • Seagull
  • Posts: 11654
  • class keyThumper<T>:ILazy<T>
Re: .NET Documentation questions.
« Reply #24 on: November 25, 2015, 10:28:26 AM »
Code samples are also handy. It's all well and good to talk about how to use something but I'm sure I am not the only one who sees an actual example and says "oh, that's what they meant there". They are also handy for showing best practices.

I'll have to disagree on that.  Short, concise code samples showing an optional parameter, object, etc. don't necessarily follow best practices such as error handling.  Perhaps a two-pronged approach: short examples local to the object at hand, plus several overall examples, referenced in multiple places, that also demonstrate overall coding techniques?

I'm a big advocate of samples and I agree with David's comment here.
I think that the samples belong in the same document ( or document collection) as the documentation.
2 reasons :
Makes reference linking more efficient
The samples can be updated and/or corrected and re-released with the documentation.
This way we don't end up with snippets scattered from here to breakfast ; all in various states of 'correctness'

The forums and blogs can then be used to help solve efficiency and edge problems instead of second guessing about the documentation.

 
kdub, kdub_nz in other timelines.
Perfection is not optional.
Everything will work just as you expect it to, unless your expectations are incorrect.
Discipline: None at all.

CADbloke

  • Bull Frog
  • Posts: 342
  • Crash Test Dummy
Re: .NET Documentation questions.
« Reply #25 on: November 26, 2015, 03:40:04 PM »
I totally agree with David & Kerry. A comprehensive, well done example is far more useful than a snippet. It is great to see things in context and a complete example is the best way to show how to do it properly.

Docs for methods, properties etc should point to a line in the example code.

Chumplybum

  • Newt
  • Posts: 97
Re: .NET Documentation questions.
« Reply #26 on: November 26, 2015, 05:31:28 PM »
something along the lines of CodePath (maybe?): https://guides.codepath.com/android

Kerry

  • Mesozoic relic
  • Seagull
  • Posts: 11654
  • class keyThumper<T>:ILazy<T>
Re: .NET Documentation questions.
« Reply #27 on: November 26, 2015, 08:40:10 PM »
something along the lines of CodePath (maybe?): https://guides.codepath.com/android

That would be excellent Mark.
... but I think and  I'm sure AutoDesk would agree : that would be mixing our expectation and AutoDesks capability.

kdub, kdub_nz in other timelines.
Perfection is not optional.
Everything will work just as you expect it to, unless your expectations are incorrect.
Discipline: None at all.

CADbloke

  • Bull Frog
  • Posts: 342
  • Crash Test Dummy
Re: .NET Documentation questions.
« Reply #28 on: November 29, 2015, 04:59:26 PM »
What would also be wonderful is if the web team at Autodesk could Internet properly, or at least learn what a permalink is.

How good would it be if a URL like www.autocad.com/api/2016/dotnet/DatabaseServices/Database worked and never changed? Then the docs could live online, be discoverable, up-to-date and also easily accessible by a simple local link-builder that could be written for anything (eg. a Visual Studio plugin).

I tried Googling "Autodesk.AutoCAD.DatabaseServices.ObjectId" - the closest to any sort of canonical documentation I found was http://docs.autodesk.com/CIV3D/2014/ENU/API_Reference_Guide/html/b16967c7-44ea-d59c-bf26-486269d9e717.htm - GUID in a URL. Golf clap.

Jeff H

  • Needs a day job
  • Posts: 6144
Re: .NET Documentation questions.
« Reply #29 on: December 07, 2015, 05:06:57 PM »
I'm sure a number nerds at Microsoft have good reason for using this and messed with it a little and seems to work nicely, gives you live docs and pdf to download, etc., but lets development team and users communicate while documentation is being created.

https://github.com/aspnet/Docs/blob/master/CONTRIBUTING.md
https://docs.asp.net/en/latest/