Streamlining the Development Process: The API Jim Polubinski jpolubindirectvinternet.com

1
Streamlining the Development Process The
APIJim Polubinskijpolubin_at_directvinternet.com
2
Introduction

• There is no such thing as the perfect,
  no-need-to-tune piece of software all companies
  have the challenge of providing compatibility and
  flexibility in their products. It needs to be
  flexible so it can be hooked into it, or tuned
  to fit specific needs. It needs to be
  compatible so it can run cross-language,
  cross-version, cross operating system, etc.

3
Introduction (contd)

• This is no small feat. The software must be
  well-thought out to provide compatibility,
  functionality, efficiency, and flexibility. It
  must be tested to ensure that it has minimal (or
  zero!) defects when going out to a user, and it
  must be palatable enough to the user so they will
  use it (i.e., something too complex wont be
  used).

4
Introduction (contd)

• One way to introduce flexibility and
  compatibility is an Application Programming
  Interface (API). If this is sufficiently
  documented and tested, it may provide a long life
  for the software, and prove useful for the user.
  Note that an API not necessarily be strictly an
  external interface there can be private
  interfaces into a subsystem, for example.

5
Introduction (contd)

• The API should be built on the requests and input
  of users (or those who interact with users). An
  API that doesnt meet a customers needs isnt an
  API. This includes the testing group, support
  group(s), and product management. If the API
  isnt understood from the perspective of the end
  user, there may be additional calls to support to
  fix a broken API, even though the API was
  programmed to a specification. Those
  evangelizing the products should be able to
  describe APIs, and demonstrate their use.

6
A Successful API Summary

• It needs to be
• -- More intuitive to people not familiar with
• low-level computer details
• -- More flexible to allow greater use
• -- More reliable, especially as the underlying
  
• technology is improved (basically, new
• products have to support the same
  functionality)
• -- Available for inspection and comments from
  internal and external sources
• -- Clearly and accurately documented

7
Has Java Demonstrated a Solution?

• The Java programming language has solved this
  problem in some ways. Most notably, the javadoc
  tool that ships with the JDK allows documentation
  to derive directly from the source code. This is
  viewable by anyone who has a web browser, and has
  positive impact on development (the spec could be
  right in the code!).

8
javadoc Review

• What is javadoc?
• javadoc is a program provided with the Java
  sdk. It reads java files, looking at comments,
  identifying special tags, and generates html code
  based on the content.

9
javadoc An Example

• In Test.java
• Package edu.depaul.se690.foobar
• /
• This class shows javadoc.
• _at_author Jim Polubinski
• /

10
javadoc .. An Example (contd)

• public class Test
• /
• This method does nothing.
• _at_params none
• _at_since version 1.0
• /

11
javadoc An Example (contd)

• Generated HTML

12
Javadoc Benefits

• This has numerous benefits
• -- People can see the most current doc,
• and comment on it
• -- It could be improved very quickly
• -- Development has a clear direction (the
• spec is right there in the code!)
• -- Testing knows what the API does
• -- Users are able to view the
• spec and decide if they
• needed it

13
javadoc Issues

• This is a good start, but possibly not the
  best solution. First, not all source code is
  Java javadoc wont work in those environments.
  Even if it did, HTML (with its popularity due to
  web browsers), may not be appropriate for some.
  People (field SEs, for example) feel HTML isnt
  a great presentation medium, especially if the
  document is presented to someone higher in the
  chain than a developer.

14
My Proposition

• What is really needed is a generic source code
  documentation system. It should output in a
  format that allows simple transformations to get
  the right view, and should not be tied to a
  particular language.

15
Introducing srcdoc

• Srcdoc is a tool I created to address the
  problems discussed. Its goals
• -- Easy setup
• -- Easy configuration
• -- Easy use
• -- Platform and language independence
• -- Provide a way for developers to think about
  their code

16
Srcdoc The Basics

• Srcdoc will read in a source file, looking for
  comment blocks (known as an xml region in the
  source for srcdoc), and generate XML based on the
  found blocks.
• To handle language independence, srcdoc uses a
  configuration file to tell it how a comment block
  starts, ends, and what the lines are separated
  by.
• Srcdoc will generate xml files in a directory the
  user specified, currently one xml file per input
  file. This can be relaxed, I think, to one file
  per tool invocation.

17
What srcdoc is not

• -- Not a javadoc replacement (doesnt recognize
  javadocs tags)
• -- Does not perform transformations on the
  source file
• -- Not a lexical/sematic analyzer (compilers
  already exist!)

18
A Word on Design

• The tool itself is written in C. It uses no
  constructs that could cause compilers to get into
  trouble (templates, for example). It was written
  in C because all computer systems come with a
  program loader, and usually a C compiler. If
  it were written in another language which relies
  on an interpreter or runtime, the ease of use
  design goal would be violated (user needs to
  install a runtime and/or interpreter).

19
A Word on Design (contd)

• Since the tool will be reading and writing
  files, it was imperative that a file interface
  was introduced. The C runtime is almost
  sufficient, but because there are slight name
  mangling differences, I chose to build a File
  interface instead. This is in some regards
  better, because the filesystem may be the
  bottleneck for some operating systems, the CRT
  can be bypassed with faster system calls.

20
A Word on Design (contd)

• Some tags were chosen for the default in
  srcdoc. This was done in an arbitrary way, based
  on personal experience. These tags are
• class (attribute name)
• subelem comment, description, version
• method (attribute name)
• subelem returnType, param, example,
  className, comment
• globalFunction (attribute name)
• subelem returnType, param, example, comment

21
A Word on Design (contd)

• The tool is language-agnostic, and has no
  knowledge of user preferences. Using the
  configuration file, the user tells it how they
  delimit a comment region in their code. For
  example, a C user may say that a region starts
  with /, ends with /, and is separated by
  . Although srcdoc will recognize any
  character sequence, its best to choose something
  along the lines of the commenting mechanism
  native to the language. Recall that srcdoc does
  no transformations on the source, so not
  following this guideline will probably lead to
  syntactical errors.

22
A Word on Design (contd)

• For the default behavior (I will later describe
  a different mechanism have patience), once an
  xml region has been found, a class called an
  XmlTransformer takes the region and maps the
  tokens into XML. This is very specific to the
  choice of tokens in the source code (e.g.,
  class). The result is then outputted (through
  the File interface) into an XML document in the
  specified output directory (. If not specified).

23
An Example

• -- Usage
• -- Java
• -- C
• -- Interactive Python

24
Improving Usability

• Arguably, the goal of easy configuration isnt
  met. After all, choosing tags that may better
  suit someone isnt easy. It would require
  writing an XmlTransformer to do the mapping.
  While not terribly difficult, its a chore not
  many would want to do, and violates the ease of
  use goal.

25
Improving Usability Solution 1

• One solution would be to provide a scripting
  language that allows the conversion of tokens to
  XML elements. This idea is still in the planning
  stage. It seems fairly complex, and maybe not
  worth the effort.

26
Improving Usability Solution 2

• An alternative strategy, implemented in this
  version, is to allow a simple format translated
  directly into XML. The format consists of the
  following
• ltbeginTokengt
• ltsepgt (subelementOfDocumentRoot)
• ltsepgt (elementvalue)
• ltendTokengt

27
Improving Usability Solution 2

• As an example
• /
• class
• name Foobar
• version 1.0
• public yes
• /

28
Improving Usability Solution 2

• This would map directly into
• lt?xml version1.0gt
• lt!DOCTYPE srcdoc SYSTEM srcdoc.dtdgt
• ltsrcdocgt
• ltclassgt
• ltnamegt Foobar lt/namegt
• ltversiongt 1.0 lt/versiongt
• ltpublicgt yes lt/publicgt
• lt/classgt
• lt/srcdocgt

29
Improving Usability Solution 2

• This solution is very extensible, in the sense
  that customization is easily achievable. An
  organization can choose the tags that will best
  suit them, and have srcdoc create the right
  documents. As a side-effect, it is a mechanism
  for the organization to get together to define
  the tags they would like/need, and not be
  hindered by the pre-defined tags.

30
Improving Usability Solution 2

• Example c

31
Summary

• Srcdoc is a tool that will encourage
  communication between engineering and the
  software users. Although there are issues that
  need addressing, overall it serves its purpose
  immediately, with little intervention on the part
  of the user. It meets its goals of being
  flexible, platform independent,
  language-agnostic, and easy use.

32
Questions