Documentation in the source code (for AutoComplete)

[Ricardo JL Rufino]

Hello,

I'm working on AutoComplete system.

It's getting cool, now what would be really cool would be the documentation from the autocomplete (as in Eclipse)

I was able extract the documentation of the methods, but we do not have the documentation in the code yet.

I wonder if any of candidate to document at least the Arduino.h.

[Ricardo JL Rufino]

PS: Attached hereto picture of how it should be.

Following the JavaDoc style

[Ricardo JL Rufino]

PS: must also name the parameters (see attached image)

Em terça-feira, 2 de dezembro de 2014 10h35min50s UTC-3, Ricardo JL Rufino escreveu:

[PeterFeerick]

Hi Ricardo,

Am I right in understanding that you would like Javadoc commenting for functions in Arduino.h?

Something like this? It's been a while since I did javadoc.

/**
 * Configures the specified pin to behave either as an input or an output
 * @param pin The number of the pin whose mode you wish to set
 * @param mode INPUT, OUTPUT or INPUT_PULLUP
 */
void pinMode(uint8_t pin, uint8_t mode);

/**
 * Reads the value from a specified digital pin, either HIGH or LOW
 * @param pin Number of the digital pin you want to read
 * @return    HIGH or LOW
 */
int digitalRead(uint8_t pin);

instead of just

void pinMode(uint8_t, uint8_t);
int digitalRead(uint8_t);

I can probably have a look at that tomorrow, as it's just a matter of pulling the variable names from wiring_analog.c , wiring_digital.c, etc  and then reformatting the notes from the reference pages.

Cheers,
Peter

--
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

---

This email has been checked for viruses by Avast antivirus software. www.avast.com

[Ricardo JL Rufino]

Hi, Peter.

It is just that!

I think it would be interesting also put a link to reference.

And standardize the values of the accepted parameters (to be able to do something interesting)

/**

 * Configures the specified pin to behave either as an input or an output

 * @reference PinMode

 * @param pin The number of the pin whose mode you wish to set

 * @param mode {INPUT, OUTPUT, INPUT_PULLUP} - description

 */

void pinMode(uint8_t pin, uint8_t mode);

With the link (@reference) could bridge for more complete reference

[c.ma...@bug.st]

Il 03/12/2014 19:48, Ricardo JL Rufino ha scritto:
> Hi, Peter.
>
> It is just that!
>
> I think it would be interesting also put a link to reference.
> And standardize the values of the accepted parameters (to be able to do
> something interesting)
>
> /**
> * Configures the specified pin to behave either as an input or an output

> * *@reference PinMode*

> * @param pin The number of the pin whose mode you wish to set

> * @param mode *{INPUT, OUTPUT, INPUT_PULLUP}* - description

> */
> void pinMode(uint8_t pin, uint8_t mode);
>
>
> With the link (@reference) could bridge for more complete reference

Hey Ricardo!

until now we didn't put documentation in the source code but if the IDE,
at some point, will be able to show the reference while you type I guess
that this will be a very strong incentive to do so! :-)

Thanks also for the "link" hint, very nice idea.

C

[Ricardo JL Rufino]

Just to have an idea, can be like the image.

ON CTRL+SPACE

ON Mouse OVER

In this case (img 2) I'm extracting this contents from the html files that are comes with the IDE and draw the part of the text dynamically. (very costly)

I could not identify a pattern name for these references of any files. Some are: Serial_Println.html other: ServerPrintln.html

So it would be interesting to put in the '@reference' link in source code.

[Tom Igoe]

I would fund that invasive. If rather see it off to the side. It looks like eclipse's version, which is unworkable for me.

--
Tom Igoe
sent from phone. please excuse brevity and mistaken auto corrections

[Adrian Godwin]

If you do that, could you make it appear only on a keypress please ? I  strongly dislike environments which constantly pop up information  unasked. It makes moving around a page an annoying minefield of hotspots to avoid.

[Tom Igoe]

Typo in my mail. I meant “I would find that invasive.” I agree with you, Adrian.

t.

[Brian MacLeod]

Just make it an option you can turn on or off.

 

BMac

 

From: Tom Igoe [mailto:t.i...@arduino.cc]
Sent: Friday, December 05, 2014 7:33 AM
To: devel...@arduino.cc
Subject: Re: [Developers] Re: Documentation in the source code (for AutoComplete)

 

Typo in my mail. I meant “I would find that invasive.” I agree with you, Adrian.

 

t.

On Dec 5, 2014, at 4:24 AM, Adrian Godwin <artg...@gmail.com> wrote:

If you do that, could you make it appear only on a keypress please ? I  strongly dislike environments which constantly pop up information  unasked. It makes moving around a page an annoying minefield of hotspots to avoid.

On Fri, Dec 5, 2014 at 12:14 AM, Tom Igoe <t.i...@arduino.cc> wrote:

I would fund that invasive. If rather see it off to the side. It looks like eclipse's version, which is unworkable for me.

--
Tom Igoe
sent from phone. please excuse brevity and mistaken auto corrections

On Dec 4, 2014 4:35 PM, "Ricardo JL Rufino" <ricardo....@gmail.com> wrote:

Just to have an idea, can be like the image.

 

 

ON CTRL+SPACE

 

 

 

 

 

ON Mouse OVER

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

In this case (img 2) I'm extracting this contents from the html files that are comes with the IDE and draw the part of the text dynamically. (very costly)

 

I could not identify a pattern name for these references of any files. Some are: Serial_Println.html other: ServerPrintln.html

So it would be interesting to put in the '@reference' link in source code.

 

 

 

--
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

 

--
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

 

--
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

[Tom Igoe]

Even optional code has to be maintained. So just making it an option has consequences.

I’m not opposed to autofill, and I think a context-sensitive help is a good idea, but I don’t care for this particular implementation of it. I’d prefer to see the context-sensitive help in another pane rather than an overlay. As for autofill, I’ve not seen an implementation I really like yet, so I can’t offer an alternative there. 

t.

On Dec 5, 2014, at 7:33 AM, Brian MacLeod <BMac...@FIRSTSOLAR.COM> wrote:

Just make it an option you can turn on or off.

 

BMac

 

From: Tom Igoe [mailto:t.i...@arduino.cc] 
Sent: Friday, December 05, 2014 7:33 AM
To: devel...@arduino.cc
Subject: Re: [Developers] Re: Documentation in the source code (for AutoComplete)

 

Typo in my mail. I meant “I would find that invasive.” I agree with you, Adrian.

 

t.

On Dec 5, 2014, at 4:24 AM, Adrian Godwin <artg...@gmail.com> wrote:

If you do that, could you make it appear only on a keypress please ? I  strongly dislike environments which constantly pop up information  unasked. It makes moving around a page an annoying minefield of hotspots to avoid.

On Fri, Dec 5, 2014 at 12:14 AM, Tom Igoe <t.i...@arduino.cc> wrote:

I would fund that invasive. If rather see it off to the side. It looks like eclipse's version, which is unworkable for me.

--
Tom Igoe
sent from phone. please excuse brevity and mistaken auto corrections

On Dec 4, 2014 4:35 PM, "Ricardo JL Rufino" <ricardo....@gmail.com> wrote:

Just to have an idea, can be like the image.

 

 

ON CTRL+SPACE

 

<~WRD000.jpg>

 

 

 

 

ON Mouse OVER

 

<~WRD000.jpg>

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

In this case (img 2) I'm extracting this contents from the html files that are comes with the IDE and draw the part of the text dynamically. (very costly)

 

I could not identify a pattern name for these references of any files. Some are: Serial_Println.html other: ServerPrintln.html

So it would be interesting to put in the '@reference' link in source code.

 

 

 

-- 
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

 

-- 
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

 

-- 
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

-- 
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

[Brian MacLeod]

Yeah if you are going to supply the feature part of the baggage it carries is the option to enable/disable it.

Then you can turn off if annoying or dysfunctional, let the user decide what kind of experience they want .

[Ricardo JL Rufino]

This will only appear if the user hold the CTRL. Certainly would be a bag you be typing and stay open popups.

And also when you hold the CTRL and CLICK will open the documentation in the Browser.

So would be good that way?

Ricardo JL Rufino

----------------------------------------------------------------------
CriativaSoft - Desenvolvimento de Sistemas com Qualidade
Analista e Engenheiro de Software

Skype: ricardojlrufino

Linkedin: br.linkedin.com/pub/ricardo-rufino/5a/696/81a

[Tom Igoe]

Not to me. It’s not the trigger mechanism I don’t care for, it’s the implementation. As I said, I don’t like the help pane floating over the window, and I don’t like the autofill window popping up. If we’re going to implement these features, I would want to implement them in a way I *would* use them when I need the feature.

t.

[Brian MacLeod]

Auto complete as you type isn’t an option?

[Tom Igoe]

In the images that were posted, I didn’t see that as an option. If you have an implementation of that, I would take a look at it and offer an opinion.

t.

[c.ma...@bug.st]

Il 04/12/2014 22:35, Ricardo JL Rufino ha scritto:
> Just to have an idea, can be like the image.

> *ON CTRL+SPACE*

Wow, Ricardo, that's really impressive!

> *ON Mouse OVER*

Displaying the reference on "Mouse OVER", like a tooltip, maybe is too
much, in general we try to avoid intrusive changes like this. Currently
there is a "find in reference" in the right-click contextual menu, what
about adding a keyboard shortcut (F2?) to that?

Opening the reference in a side-tab would be great too but I guess this
requires an amount of extra work.

The auto-complete suggestions, if I understand correctly, are opened
only if the user press CTRL+SPACE (or CMD+SPACE on mac?), so they looks
good to me.

> I could not identify a pattern name for these references of any files.
> Some are: Serial_Println.html other: ServerPrintln.html
> So it would be interesting to put in the '@reference' link in source

We use the keywords.txt file to match keyword<->reference page. The
names of the html files comes from the name of the wiki pages used
originally on the arduino.cc reference site so, unfortunately, it
doesn't exists a fixed rule to translate a keyword to the corresponding
reference page.

Moreover the html reference distributed on the Arduino IDE is outdated,
and must be refreshed with the latest contents available on the website.
I know that there is a script in the repository to regenerate the
documentation snapshot. I never tried it, I will check that if it's
still working.

C

[c.ma...@bug.st]

Il 05/12/2014 13:58, Tom Igoe ha scritto:
> In the images that were posted, I didn’t see that as an option. If you
> have an implementation of that, I would take a look at it and offer an
> opinion.

As I understand, auto-complete suggestions appears only if you press
CTRL+SPACE or CMD+SPACE, so "optional" here means that they are
displayed only with explicit user request.

A demo app of RSyntaxTextArea is here:

http://fifesoft.com/autocomplete/

if you go down on the link: "Try the WebStart demo"

(on macosx you should probably allow unsigned 3rd pary app from the
preferences panel "Security & Privacy")

C

[Tom Igoe]

I saw the earlier images of that, Cristian, thanks. But I think perhaps I’m not being clear.

I don’t like the idea of a box popping up to suggest completion. It doesn’t matter that it’s optional. It doesn’t matter that it’s only displayed when the user explicitly requests. I find it invasive and unattractive, even when I do choose it.

An alternative, which Brian suggested, is that auto-correct suggestions appear in the edit window, not in a pop-up window. I assume these suggestions would *also* appear only when the user explicitly requests, perhaps on CTRL+SPACE or CMD+SPACE. I think that may be a less unattractive solution. I’ve seen some (not all) versions of that which work well. It’s possible (though not a given) that this would be a better alternative.

t.

[Paul Stoffregen]

On 12/05/2014 05:19 AM, Tom Igoe wrote:
> I don’t like the idea of a box popping up to suggest completion. It doesn’t matter that it’s optional. It doesn’t matter that it’s only displayed when the user explicitly requests. I find it invasive and unattractive, even when I do choose it.

How about when you use a smart phone or tablet or modern word processor?

They're all using a pretty consistent auto-complete interface these
days. Even if you don't personally like it, there's a lot to be said
for consistency and familiarity that non-programmers will bring with
them from using smart phones.

[Tom Igoe]

On Dec 5, 2014, at 8:22 AM, Paul Stoffregen <pa...@pjrc.com> wrote:

On 12/05/2014 05:19 AM, Tom Igoe wrote:

I don’t like the idea of a box popping up to suggest completion. It doesn’t matter that it’s optional. It doesn’t matter that it’s only displayed when the user explicitly requests. I find it invasive and unattractive, even when I do choose it.

How about when you use a smart phone or tablet or modern word processor?

Some of those are less invasive to me, though it all depends on timing, IMO. I prefer the ones that do the auto-correct in-editor, and delay a second or so before they implement it. I don’t care for Android’s version, it’s too fast, but I don’t notice it as much on iOS

They're all using a pretty consistent auto-complete interface these days.  Even if you don't personally like it, there's a lot to be said for consistency and familiarity that non-programmers will bring with them from using smart phones.

There are a variety of differences, actually. The size of the pop-up window makes a difference. Whether it’s in a popup or in-editor makes a difference. How long the OS delays before popping it up makes a difference. Whether it suggests one term or a list makes a difference.

My objection to the version offered so far is that it uses a pop-up window and presents a list. Compare it to how OSX does it, with just one term, like so:

Or consider the option that Brian suggested, popping up the term in-editor, rather than in a window. There are many options, they’re not all the same.

 

t.

[Ricardo JL Rufino]

"My objection to the version offered so far is that it uses a pop-up window and presents a list"

I think interesting show a list because not always the person knows the name of the available methods, I even found several methods that did not know existed and I was happy "because I learned a little more Arduino with autocomplete ..." The same happened when I was learning java programming.

Almost 95% of the IDEs that I know use a similar model. Even the online IDEs are using it .. (ex: https://c9.io)

"Personally" I only see quality in an IDE if it offers completion suggestions and some kind of built-in documentation.

I prefer that the completion suggestions only appears when the user request ( CTRL + SPACE / similar).

It would be the way of the user asking for help for the IDE, not the IDE be getting in the way the user wants to code (it can be an experienced user)

Believe that are the experiences that we have that generate a reference of CORRECT or FAULTY. So it varies from the experiences of each person... 

PS: I apologize for the errors of English is not my native language. 

2014-12-05 10:30 GMT-03:00 Tom Igoe <t.i...@arduino.cc>:

My objection to the version offered so far is that it uses a pop-up window and presents a list

[Federico Fissore]

c.ma...@bug.st ha scrito il 05/12/2014 alle 13:59:

> Il 04/12/2014 22:35, Ricardo JL Rufino ha scritto:
>> Just to have an idea, can be like the image.
>> *ON CTRL+SPACE*
>
> Wow, Ricardo, that's really impressive!
>
>> *ON Mouse OVER*
>
> Displaying the reference on "Mouse OVER", like a tooltip, maybe is too
> much, in general we try to avoid intrusive changes like this. Currently
> there is a "find in reference" in the right-click contextual menu, what
> about adding a keyboard shortcut (F2?) to that?

I'm not happy with that mouse over either, for the reasons you all have
already mentioned.

I can't wait to try it, though!
Ricardo, once you'll come up with a pull request, our bot will build
your code, and we'll be able to try it on real code and see how it
really feels.
With all the gathered feedback, we'll be able to tune it appropriately.

Regards

Federico

[Ricardo JL Rufino]

Federico, 

I'm focusing on autocomplete, the embedded documentation was an idea I had and figured out how to ..

And she being extracted from the source code, could generate a stimulus for other libraries developers  to comment their code, since they can now appear for "normal users"

I think this may have a positive impact on new libraries. Or I could be dreaming ...

Pretty soon finalize and make a pullrequest.

Ricardo JL Rufino

----------------------------------------------------------------------
CriativaSoft - Desenvolvimento de Sistemas com Qualidade
Analista e Engenheiro de Software

Skype: ricardojlrufino

Linkedin: br.linkedin.com/pub/ricardo-rufino/5a/696/81a

--
You received this message because you are subscribed to the Google Groups "Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to developers+unsubscribe@arduino.cc.

[Ricardo JL Rufino]

How to know what the flags/macros that are enabled? for each board?

I Need to know if for example X model has the flag 'UBRR0H' 

Is there any place you can get this information? 

PS: I do not know if it would be cool always show Serial 1, 2, 3

Ex:

 

#if defined(UBRRH) || defined(UBRR0H)
  extern HardwareSerial Serial;
  #define HAVE_HWSERIAL0
#endif
#if defined(UBRR1H)
  extern HardwareSerial Serial1;
  #define HAVE_HWSERIAL1
#endif
#if defined(UBRR2H)
  extern HardwareSerial Serial2;
  #define HAVE_HWSERIAL2
#endif
#if defined(UBRR3H)
  extern HardwareSerial Serial3;
  #define HAVE_HWSERIAL3
#endif

Ricardo JL Rufino

----------------------------------------------------------------------
CriativaSoft - Desenvolvimento de Sistemas com Qualidade
Analista e Engenheiro de Software

Skype: ricardojlrufino

Linkedin: br.linkedin.com/pub/ricardo-rufino/5a/696/81a

[Federico Fissore]

I would leave that for a second iteration.

Start showing all Serials. Only then we'll look for optimizations and
improvements.

Regards

Federico

Ricardo JL Rufino ha scrito il 06/12/2014 alle 23:34:

[Ricardo JL Rufino]

Completed implementations (90%), I posted the results and the link on another email

[Ricardo JL Rufino]

Hello, someone has already made adjustments in Arduino.h placing the names of parameters and / or documentation?

I have a lot of people here in Brazil, anxious to test these improvements..

[Mikael Patel]

Hi! You could test Cosa. This Arduino OOP framework is documented according to the doxygen tags. Please see  http://embeddedcomputing.weebly.com/cosa-an-alternative-framework-for-avr-boards.html for similar support in XCode. 

Cheers! Mikael

[Ricardo JL Rufino]

Hello,

Sorry I ended up without answering this email and just saw now when seeking some old emails.

I ended up creating a ticket

https://github.com/arduino/Arduino/issues/2692

You can suggest your proposal there?

Thank U.

--

You received this message because you are subscribed to the Google Groups "Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.