APIMiner: Documentando APIs com exemplos

[João Eduardo Montandon]

Prezados, boa tarde,

Gostaríamos de divulgar a ferramenta Android APIMiner que está
publicamente disponível em:

java.llp.dcc.ufmg.br/apiminer

A ferramenta está sendo desenvolvida como parte de minha dissertação 

de mestrado em Ciência da Computação na UFMG.

Basicamente, essa ferramenta disponibiliza uma documentação para a API 

do Android idêntica à documentação original, porém com milhares  de exemplos 

reais de uso dos métodos da API. Esses exemplos foram garimpados 

automaticamente a partir do código fonte de aplicações Android de código 

livre (tais como wordpress, ZXing Barcode Scanner, entre outros).

Estamos disponibilizando uma primeira versão publicamente para que a comunidade 

possa utilizar e sugerir ideias/melhorias a respeito da ferramenta.

Qualquer dúvida/curiosidade a respeito sintam-se a vontade para entrar 

em contato conosco.

Desde já agradecemos pelo uso e divulgação do Android APIMiner.

Atenciosamente,

João Eduardo Montandon
Grupo de Pesquisa em Engenharia de Software Aplicada
Depto de Ciência da Computação
Universidade Federal de Minas Gerais
http://dcc.ufmg.br/~joao.montandon/

[Cláudio B.]

Olá João,

Realmente é uma ferramenta muito interessante e muito valiosa para
quem está aprendendo a programar em Android.

Algumas dicas:
- verificar se o texto do exemplo é o mesmo e filtrá-lo para que não
apareça repetido (veja android.os.Vibrator método cancel há 3
exemplos, sendo que poderia ser 2 só )

- usar repositórios do github para ter mais exemplos (como você fez a
extração de exemplos ?)

- prover lugar para adição de novos repositórios fornecidos pelos
usuários para que o sistema possa coletá-los : git clone url_repo, svn
checkout url_repo

- simplificar layoutdo html de "examples"
ao invés de um botão mais um texto auxiliar sugiro o seguinte:
se não há exemplo: o botão "Sem exemplos" = aciona um form de captura
de url de código de exemplo
se há exemplos: o botão fica "X exemplos" e não há necessidade do texto auxiliar



[]'s

Cláudio B.


Em 14 de setembro de 2012 16:11, João Eduardo Montandon
<edu.mo...@gmail.com> escreveu:

> --
> --
> Para enviar mensagem para o grupo, envie email para gtu...@googlegroups.com
> Para não receber mais mensagens deste grupo, envie um email para
> gtugbh+un...@googlegroups.com
> Para saber mais, visite http://groups.google.com/group/gtugbh
>
>
>

[Kimo]

Gostei da iniciativa. Muito bom!

--

[João Eduardo Montandon]

Olá Cláudio, tudo bem??

Obrigado pelas dicas!! Você deu algumas ideias interessantes que podemos utilizar para melhorar a ferramenta.

- Em relação ao caso dos exemplos repetidos, eu dei uma olhada e realmente o exemplo no final das contas é mesmo. O que explica sua repetição é que ele foi coletado em métodos diferentes (um foi coletado no método onPause(), outro coletado no PlayAlarm()). Mas de qualquer forma estamos estudando alternativas para atenuar esses casos (como por exemplo tentar agrupar exemplos muito similares).

- Com relação ao repositório de sistemas, no momento nós consideramos sistemas que estejam disponíveis publicamente em repositórios web (google code, github, bitbucket, etc.) que utilizam um sistema de controle do tipo git, svn, hg, cvs e bazaar. Basicamente, nós passamos o link do repositorio deste sistema e o APIMiner baixa o sistema e extrai os exemplos do sistema fornecido.

- Nós até pensamos em disponibilizar uma página onde os próprios desenvolvedores pudessem submeter seus sistemas para o APIMiner, mas preferimos monitorar por um tempo desempenho da infraestrutura onde a ferramenta está localizada. Essa ideia é realmente muito boa e ajudaria muito a manter esse "ecosistema". Assim que vermos que está tudo ok e estabilizado, espero estar disponibilizando esta solução pra vocês. :)

- A sua ideia com relação a interface é muito interessante e realmente acho que poderia simplificar a interface.

Mais uma vez, muito obrigado pelas contribuições!!

Abraços,
João Eduardo Montandon
Master Computer Science Student of FUMG.
http://homepages.dcc.ufmg.br/~joao.montandon/

2012/9/14 Cláudio B. <claudi...@gmail.com>

[Murilo Saraiva de Queiroz]

Seria bom filtrar ou pelo menos indicar quais métodos têm exemplos - eu naveguei pelo sistema por cinco minutos e não achei NENHUM, todos estão "0 examples". 

Falta scroll na Panel Navigation (só tem na Tree Navigation). 

A busca não funcionou (digitei a palavra chave e apertei enter, não aconteceu nada). 

2012/9/14 João Eduardo Montandon <edu.mo...@gmail.com>

--

--
Para enviar mensagem para o grupo, envie email para gtu...@googlegroups.com
Para não receber mais mensagens deste grupo, envie um email para gtugbh+un...@googlegroups.com
Para saber mais, visite http://groups.google.com/group/gtugbh
 
 
 

--
Murilo Saraiva de Queiroz, MSc

Hardware Engineer at NVIDIA

[Daniel Novy]

Muriloq, naveguei pela classe Dialog e lá tem vários exemplo. Mas realmente, eu diria que existem somente uns 10% de métodos com exemplos na API inteira.

De qualquer forma, achei a idéia genial. Parabéns pela iniciativa, João!

Atenciosamente,

Daniel Novy +55 (31) 8598-5791 +55 (31) 3309-9386

www.mobart.com.br

[João Eduardo Montandon]

Olá Murilo tudo bem??

Realmente temos um problema com relação a cobertura dos exemplos. Pelo fato dos exemplos serem coletados de sistemas já prontos, precisaríamos de sistemas bem diversificados para cobrir toda a API. 

Só para ilustrar, estamos no momento com 90 sistemas cadastrados, com um total de 82 mil exemplos, e 2400 de 15000 métodos foram cobertos, dando algo em torno de 15% de cobertura. O que a gente está percebendo é que para funcionalidades muito corriqueiras nós temos muitos exemplos, e para funções mais específicas estamos com dificuldade de encontrar sistemas que utilizem tais funções.

Inclusive, se vocês tiverem/conhecerem algum aplicativo que tenha na sua implementação a utilização de alguma API que não possui exemplo, que envie os dados desse aplicativo pra gente. Como pré-requisito, basta apenas o aplicativo ser código aberto e estar disponível publicamente em um sistema de controle de versão (Github, Google Code, BitBucket, etc.).

Com relação a busca, de fato ela não está funcionando. Já reportei esse bug e vamos analisar o que pode estar acontecendo.

Com relação ao scroll, realmente não tinha percebido isso. Também reportei esse bug e vou olhar o que está acontecendo.

Obrigado pelo feedback!!

Abraços,
João Eduardo Montandon
Master Computer Science Student at UFMG.
http://dcc.ufmg.br/~joao.montandon/

2012/9/18 Murilo Saraiva de Queiroz <mur...@gmail.com>

[Murilo Saraiva de Queiroz]

Como é uma versão alpha, ajudaria bastante se vocês colocassem, já na página inicial, links que levassem para casos em que há vários exemplos - assim dá para os usuários avaliarem o sistema sem precisar sair procurando... 

E sou obrigado a fazer algumas perguntas chatas (que alguém da banca de mestrado também vai acabar fazendo, então é bom já se preparar): 

Qual a diferença do seu sistema para outros como o http://www.jexamples.com ("We analyze the source code of production Java open source projects such as Ant, Tomcat and Spring and load that analysis into a java examples database designed for easy searching. You enter the name of a Java API Class you want to see example invocations of and click Search") e Koders ("Koders is a search engine for open source code. It enables software developers to easily search and browse source code in thousands of projects posted at hundreds of open source repositories.") ?  A inovação é estar integrado ao JavaDoc? Se for, o que o torna diferente de iniciativas antigas como o Java Developers Almanac (que era justamente, isso, JavaDoc anotado com exemplos)? 

Vocês planejam algum recurso social, como permitir que os usuários votem nos exemplos, colaborem com novos e construam uma reputação (como nos extremamente bem-sucedidos StackOverflow / StackExchange)? 

Como vocês lidam com direito autoral? Não é porque é open source que você pode usar de qualquer jeito; por exemplo, como saber qual a licença de cada exemplo? 

muriloq

2012/9/18 João Eduardo Montandon <edu.mo...@gmail.com>

[João Eduardo Montandon]

Olá Murilo, sem problemas!!

O que vejo como diferencial com relação as soluções que você citou é a forma de como extraímos os exemplos. Enquanto Koders e jexamples se baseiam em uma consulta textual para extração dos exemplos, nós procuramos extrair exemplos considerando a estrutura do código onde ele foi encontrado. Em pouco mais de detalhes, a nossa extração é feita utilizando uma heurística baseada em slicing de programas (o que não é feito pelo Koders e jexamples). Como resultado nós conseguimos oferecer exemplos que geralmente são mais significativos (uma vez que o slicing considera somente as linhas relacionadas a chamada do método da API), e sintaticamente corretos.

Com relação ao recurso social, nós temos muito interesse em expandir a ferramenta neste sentido. Nós esboçamos algo muito pequeno com relação a isso na versão alpha (o usuário pode dar uma nota no exemplo e esta nota influencia a posição do exemplo no ranking). Mas eu gostaria de fazer algo mais elaborado, um ecossistema mais fechado, como existente no StackOverflow por exemplo.

Com relação aos direitos autorais, ressalto que em nenhum momento nós utilizamos o código de algum sistema na nossa aplicação. No meu ponto ponto de vista, o que fazemos também é uma espécie de indexação (como é feita no Koders e jexamples), só que de forma mais enriquecida (considerando a estrutura do código). Também damos o devido crédito aos desenvolvedores do código disponibilizado como exemplo, mantendo sua referência (sistema de onde o exemplo foi retirado) disponível para o público.

[Murilo Saraiva de Queiroz]

2012/9/18 João Eduardo Montandon <edu.mo...@gmail.com>

Olá Murilo, sem problemas!!

O que vejo como diferencial com relação as soluções que você citou é a forma de como extraímos os exemplos. Enquanto Koders e jexamples se baseiam em uma consulta textual para extração dos exemplos, nós procuramos extrair exemplos considerando a estrutura do código onde ele foi encontrado. Em pouco mais de detalhes, a nossa extração é feita utilizando uma heurística baseada em slicing de programas (o que não é feito pelo Koders e jexamples). Como resultado nós conseguimos oferecer exemplos que geralmente são mais significativos (uma vez que o slicing considera somente as linhas relacionadas a chamada do método da API), e sintaticamente corretos.

Entendi. Acho importante deixar isso mais claro, já que é sua principal contribuição. A propósito, eu queria um "grep", de linha de comando mesmo, que entendesse a sintaxe do código: ao invés de retornar apenas a linha onde a expressão aparece, por exemplo, retornasse também a classe e o método, e se eu passasse um parâmetro "contexto" (ou "bloco") ele mostraria a slice de código onde a expressão aparece (e.g. se for um bloco pequeno de um if, mostrar esse bloco todo). Tem a ver com que você está fazendo, né? 

 

Com relação ao recurso social, nós temos muito interesse em expandir a ferramenta neste sentido. Nós esboçamos algo muito pequeno com relação a isso na versão alpha (o usuário pode dar uma nota no exemplo e esta nota influencia a posição do exemplo no ranking). Mas eu gostaria de fazer algo mais elaborado, um ecossistema mais fechado, como existente no StackOverflow por exemplo. 

Com relação aos direitos autorais, ressalto que em nenhum momento nós utilizamos o código de algum sistema na nossa aplicação. No meu ponto ponto de vista, o que fazemos também é uma espécie de indexação (como é feita no Koders e jexamples), só que de forma mais enriquecida (considerando a estrutura do código). Também damos o devido crédito aos desenvolvedores do código disponibilizado como exemplo, mantendo sua referência (sistema de onde o exemplo foi retirado) disponível para o público.

Eu não vi nem a questão do voto nem a referência para o projeto original porque eu não tinha conseguido encontrar nenhum exemplo... 

De qualquer forma, parabéns pela iniciativa, está interessante. 

muriloq