Topic: Managed API Rant

[Kerry]

<deleted by author>

Summary of deleted content (with expletived and derogatory remarks elided)

Where is the Managed API documentation ?

The current Help Documents are little more than a signature list.
I get more help and insight from my peers than I do from any product documentation I've seen.

We've been waiting long enough.

As a lisp programmer wanting ActiveX documentation I've been told for more than 15 years to read the VisualBasic documentatio and make my own translations.

As a DotNet developer I've been told for 6 years to read the ARX documentation and make my own translations. (or guesses)

I've had a gut full of being treated with disrespect.

calm Regards
kdub

[MP]

Must be something wrong with me, I've never felt like I was "being treated with disrespect" because I had to sleuth out info, tho I could certainly see how it could be mondo frustrating for some.

[Kerry]

Hi Michael,
I relish sleuthing as much as you do.
Some people are not as good at it as you and I.

I'm imagining how much more productive we (as a group) could be if we didn't have to do quite so much of it.

I've had several communications from people suggesting that they would have been unable to solve issues without the posts at TheSwamp and peer to peer support received here and at the Discussion Group ...

it's not the act of sleuthing that's frustrating, it's the ongoing necessity.

Part of my personal difficulty is that I haven't done a lot of keybashing in the last 12 months and I'm subject to the 'use it or lose it' syndrome .... this means re-researching stuff ... not productive.

Be well

[Keith™]

Kerry, I happen to agree with you 100% .. if there were better documentation, it would be infinitely easier to develop solutions with the tools available.

I regularly pound out code that makes use of poorly documented API calls, managed or not ... what is even more infuriating is when you develop a solution predicated on one of these undocumented API calls and it is later changed and causes the code to fail intermittently.

In one application I spent two years developing, the managed API didn't ... in the end, much of the functionality had to be removed because of the errors generated from "managed" code. Supposedly, MS is working on a fix to the memory error not being propogated, but I don't hold out much hope.

[MP]

Can't refute a single thing is subsequent posts.

[SEANT]

I suppose it makes sense economically; sleuthing is the price we pay for not enrolling in ADN.  That statement does presume significant additional resources to enrollees.  Are there any ADN members here willing to give an opinion?

Conceivably, we derive some benefit from our programming skill, regardless of our position as a professional programmer.  The benefit is likely enhanced due to the price of admission.

I think it safe to say that most of the Swamp.org members enjoy a benefit that is not strictly financial.  As a matter of fact, this site would probably be considerably less lively if the task of learning the APIs were considerably less difficult.

[Kerry]

< .. >  Are there any ADN members here willing to give an opinion?[/i]

Yes. And I have.

[Kerry]

< .. >
 As a matter of fact, this site would probably be considerably less lively if the task of learning the APIs were considerably less difficult.

I can't really agree with this. I think we would stay lively and have moved on to more challenging topics.

[SEANT]

Yes. And I have.

A quick search hasn’t returned anything definitive – though it was quick:  What is your opinion of ADN?

I can't really agree with this. I think we would stay lively and have moved on to more challenging topics.

Perhaps.  The Swamp was a welcome find for me due to the aforementioned reasons.  That common goal has focused a competent and eclectic group of people.

[Kerry]

< .. >  What is your opinion of ADN?

If the ADN was an independent service I doubt it would survive.
Having access to various versions and builds is a big help sometimes.
The ADN is not some magical storehouse of chants and spells. The knowledge base is really just a refined collection of some of the questions asked and answered .. handy sometimes, but I don't think the interesting questions and answers ever see the light of day.
The answers to any questions I've asked are sometimes helpfull .. though the wait is sometimes painfull.

This actually expands on the point I was trying to make initially.  If we had complete API documentation the ADN could be used for solving the more difficult problems that arise, rather than servicing simple "How do I .. " questions.
Actually, I'm prepared to hazard a guess that the ADN tech guys have as much trouble as we do finding out specifics about the API.

We only have to analyse the questions that are repeatedly asked here at TheSwamp , at the DicussionGroup, at Augi, at CadTutor etc to realise how much waste is being caused by not having complete documentation .... this is compounded by the fact that sometimes the answers are guesses and wrong and sometimes it takes an inordinate amount of peer patience to actually determine what the actual question really is. Any dotNet AutoCAD internet search will currently return more out of date information or incorrect/halfcorrect guesses or pleas for help that it returns usefull relevant data.

There are several blogs that help to fill some of the gaps with insightful posts ... but my argument is that they only partially fill gaps in information that should be available in one, or a series of coordinated documents.


I probably should just revise my expectations, but I'm sure they are also the expectations of a lot of other people who aren't so forthcoming.

Regards and apologies if your ears hurt
kdub

[SEANT]

. . . . apologies if your ears hurt
kdub

Quite the contrary, it is posts like this one that make the swamp worth the price of admission – even if it had a price of admission.


I have had fairly limited contact with Autodesk personnel (through non-ADN channels) and can say that, in each instance, they were as helpful as they could be.  There was always this undertone, however, that the personnel were hampered in there ability to provide more assistance.  I suspect that Autodesk’s marketing and legal divisions are much more the problem with regard to an ADN tech’s ability to dole out information.

I should point out that I am somewhat of a ‘conspiracy theorist’ (actually more of an ‘emergent behaviorist’) but now that some of the ADN hierarchy are members, perhaps additional light can be shed on this matter.

[Kerry]

(actually more of an ‘emergent behaviorist’)

wow, following that thread would be a psychological diversion

[Jeff H]

One thing with ADN guys is  everyone I dealt seemed to be a smart guy, but they have direct access or just send a e-mail to the guys who are most knowledgeable with that portion of the API. Not sure how the teams are broken up but from responses it seems they basically know who or what group of guys deal or maybe even wrote that functionality of ObjectARX or AutoCAD.
 
The way I look at it is the API is so huge it would take a much more resources to keep up with documentation.
 
When looking at the .NET API they really do not add many layers to simplify it. Of course some differs and certain aspects are different but if you are trying to figure something out and looking at a  C   example is basically as good as looking at a .NET example.
 
I really do not think AutoDesk spends as many resources or places the API as a high priority as they claim.
 
On the other hand with how large and complex the API and the complexity under the hood with the resources given I wouldn't expect much more.
 
As for getting upset I do get frustrated sometimes but it does not take long to see what you will be dealing with and no one is forcing you to do it. I do not think it takes much to figure out that in the end your code has to make calls to Autocad code base so you are completely dependent and forced to deal with Autodesk's implementation.
 
In the end AutoCAD is a product and not a platform.

[It's Alive!]

I usually have a Cafe-Mocha-Vodka-Valium-Latte before reading the docs. give it a try

[Jeff H]

I usually have a Cafe-Mocha-Vodka-Valium-Latte before reading the docs. give it a try

Please no one read Daniel's post and take that serious as taking any of those will only hurt your ability to understand the information in docs.
If really want help you need a good amount of coke, crystal meth, and amphetamines.
 

[gile]

Kerry,

I agree with you and should add it's a shame that the ActiveX documentation is no more availalble since A2011 in spite of the fact that VBA is still available and Visual LISP or .NET can use this API (Autodesk recommend to migrate VBA applications to .NET using the AutoCAD COM API).

PS: when these docs exists, they're only available in English...

[ChuckHardin]

You know this is why I love this site and hate that Randall has left the circle.
At the very least with Randall you got an answer that taught you a lot about coding and he had a wealth of information about the APIs. The LL was a wonderful tool. The forum was highly helpful just as this one is. I notice a lot of the same Q&A here as there was with RR's Sites. All of you make this site one of the best on the internet not just for AutoCAD but for coding in general. TheSwamp is one of the best places to ask any coding question and replies are always fast and most of the time spot on. The only problem I have is communicating my needs. Code I can write getting the problem stated is another challenge.   

 
Thank you for all your help!

[joshua.modglin]

Not to start something else but if Autodesk asked, what would you do to the documentation? How would you change/increase/view the documentation?

[It's Alive!]

As of now, the docs for the managed API are just generated from the headers...  the comment is usually something like... This .NET class wraps the XXXX  ObjectARX class, please RTFARXDOCS 

[Jeff H]

And you see this many times
 
DbCadObj.SetGraphProtocol()
Sets the GraphProtocol
.....................................
So go to GraphProtocol definition
..........................................
 
GraphProtocol
A class that DbCadObj uses for protocals.
 
 
 ............................................................
Now go to TheSwamp.org and ask what is it.
 ...............................................................

[JohnK]

horrible docs produced from comments is no excuse imo. qt, kde, llvm, cmake, etc.

look up doxygen.

[It's Alive!]

horrible docs produced from comments is no excuse imo. qt, kde, llvm, cmake, etc.

look up doxygen.

I guess, I should rephrase, when you think using doxygen to list just the signatures in a fancy format 'is' documentation, then there is a problem   

[Kerry]

Not to start something else but if Autodesk asked, what would you do to the documentation? How would you change/increase/view the documentation?

Self contained documentation, not reliant on reading with something else.
Type Descriptions. (more than a generic 5 word sentence)
Member Descriptions: (ditto)
Usage examples.
Linked References .. for things like enumerators, typed parameters, typed returns
Do not assume that the user has a degree in Computer Science and develops full time .

Some of the examples for the old VBA documentation were quite good.

Drop the idea that VB is easier to learn than C#. Both languages are easy to learn, even if they are syntactically different in some ways ... The API's are what takes the time and effort to learn.

Add Option Strict On and Option Explicit On to all VB samples ... it may make for better translations and a more consistant code standard.

Generally the Parameter naming used in the Reference Guide is quite descriptive (good)

There was a discussion here a couple of weeks ago involving several AutoDesk luminaries (gopinatht, Stephen) The Summary was :

    1) Always use the "using" statement with the transaction object
    2) Always use the "using" statement with newly created DB Objects being added to the transaction
    3) Always using the "using" statement with DB Objects that are not added to the database
    4) You dont have to use the "using" statement with existing DB Objects opened with a transaction object

This type of information SHOULD be documented and available to everyone.

I think we all already know what constitutes effective documentation, and are aware that it will become more important as new customisers start to come to grips with dotNet.
As I said earlier, it is time to do something about it, and without further procrastination.

Regards
kdub

[Jeff_M]

Well said, Kerry. There isn't one point you made that I disagree with.

I would only expand the item list by one:
If an API is provided for a vertical product, apply the same rules to THAT documentation as well.

[Jeff H]

If an API is provided for a vertical product, apply the same rules to THAT documentation as well.

Don't get me started on MEP.
For 2012 and I think 2011 they said the hell with it and just use 2010 documentation.
 

[MexicanCustard]

If an API is provided for a vertical product, apply the same rules to THAT documentation as well.

Don't get me started on MEP.
For 2012 and I think 2011 they said the hell with it and just use 2010 documentation.

Amen brother!

Look at the online documentation for .NET, complete descriptions and multiple code examples. If it can be done for the entire Microsoft .NET API it can easily be done for AutoCAD's .NET API.

[Jeff H]

I have this feeling that most resources are probably going into a new API that will be compatible for PC and MAC

[Bryco]

The help in vba is far better. They could use that as a model for sure.  I converted all my code to C# and it took forever. Every step of the way there is some small difference that an example would have helped. Money wise the conversion was way too costly and  w/ vba still usable I wouldn't have bothered if I had known it would be so much trouble. If someone at the office wanted do a little coding I wouldn't recommend net at all. It would have to be lisp as with not too much work they could write something that gives them the itch to continue.

[Jeff_M]

Well said, Kerry. There isn't one point you made that I disagree with.

I would only expand the item list by one:
If an API is provided for a vertical product, apply the same rules to THAT documentation as well.

Looks like the Civil3D team was listening: New C3D API Help This is a HUGE improvement! But, as usual, they need some better proofreading ... in the 10 minutes I spent looking through it, I found one method that had another method's example shown, then when I tried to report it I got a new email message to compose...but no address in the "To:" line so it could not be sent.