#35 Packages.html and Overview.html

open
nobody
None
1
2012-10-10
2002-02-13
Vincent Massol
No

I believe packages.html and overview.html are the
most important javadoc documentation files as they
give a higher level view of the system. However,
developers very frequently forget them.

My suggestion is to add a check for these files as
part of checkstyle.

Thanks
-Vincent

Discussion

  • Lars Kühne
    Lars Kühne
    2002-02-13

    Logged In: YES
    user_id=401384

    Vincent,

    you'll be glad to hear that a check for package.html has
    already been implemented (RFE #466756) and will be available
    in the next release.

    I agree that a check for overview.html would also be very
    useful.

    Cheers,
    Lars

     
  • Vincent Massol
    Vincent Massol
    2002-02-13

    Logged In: YES
    user_id=22169

    Lars,

    Indeed, I'm glad to hear this ! Could we leave this RFE
    open for the overview.html case ?

    Thanks
    -Vincent

     
  • Lars Kühne
    Lars Kühne
    2002-02-13

    Logged In: YES
    user_id=401384

    Sure, we'll leave it open. However I currently have no
    really good idea how to implement it. The problem is that
    the overview file does not have to be in the same directory
    as the java files.

    The javadoc tool documentation
    (http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#overviewcomment)
    says that the overview file (not necessarily overview.html)
    can be anywhere in the filesystem. This means that you
    would have to specify the overview location as a checkstyle
    parameter, which implies that you didn't forget to write the
    overview so you don't need to check it.

    Maybe we could assume some conventions and check for
    overview.html towards the root of the filesystem for each
    java file.

    Any better ideas?

     
  • Vincent Massol
    Vincent Massol
    2002-02-13

    Logged In: YES
    user_id=22169

    Good point. However I don't think it is a problem. With
    the same reasoning you must also not forget to use the
    checkstyle ant task as part of your build file ... :-)

    Usually on projects with several persons there is someone
    (possibly acting as the QA/build manager) who is in charge
    of the build. That person can put the rule in the build
    file so that developers do not forget.

    I think setting the location manually as a checkstyle
    parameter is the best way to do it. If not specified then
    it can default to the root of the src filesystem or
    checkstyle can look for it in the specified filesystems.

    My 0.2
    -Vincent

     
  • Oliver Burn
    Oliver Burn
    2002-02-16

    Logged In: YES
    user_id=218824

    IMHO, I find supporting the overview.html check confusing
    since the overview.html can be placed anywhere. Rather
    than using Checkstyle to check for its existance - it
    would be just as easy to put a check into ANT (via a
    target), to verify the overview file exists. This would be
    a clearer approach.

    When ever I think of adding a feature to Checkstyle, the
    first thing I do is imagine what documentation I would
    write. If I find it hard to image what the documentation
    will say -- then obviously the feature is confusing and
    will confuse people.

     
  • Vincent Massol
    Vincent Massol
    2002-02-17

    Logged In: YES
    user_id=22169

    Oliver,

    I follow your line of thought. However, I still believe it
    is well within checkstyle scope (definition of checkstyle
    = "Checkstyle is a development tool to help programmers
    write Java code that adheres to a coding standard").

    Of course, it could be done (awkwardly) in Ant but then I
    would have 2 frameworks to check my coding style. I could
    also check the packages.html stuff in Ant (has it been
    removed, I can no longer find the doc for it - it was
    there yesterday). Same using "sed" for a lot of others
    checkstyle features. What I like is the goal of the tool,
    in the sense that it regroups all the checks and make it
    easy to use.

    I don't see what is difficult to understand in :

    checkOverview : Verifies the existence of an overview.html
    file. Default location is searched from within the
    specified source trees.

    checkOverviewFile : specifies where to look for the
    overview.html file. Overrides the default behaviour which
    searches for it within the specified source tree

    If you're doing a tool that checks javadoc compliancy,
    then obivously the tool should abide by the javadoc spec.
    and packages.html and overview.html are part of the spec.
    So I think it makes sense.

    Have I convinced you ? ;-)

    Thanks anyway for listening
    -Vincent

     
  • Oliver Burn
    Oliver Burn
    2002-02-17

    Logged In: YES
    user_id=218824

    An assumption being made is that Checkstyle is given
    specified source trees. This is not quite true, the engine
    in Checkstyle (the Checker class) is merely given a set of
    files to check. You cannot assume this corresponds to
    source tree.

    Since we are talking about checking for the existance of a
    single file, which is not the same as for the
    package.html file, if this feature was to be implemented,
    then the only option would be checkOverviewFile.

    TBH, I am still not convinced it would be worth the effort
    to add this check. Still, I will not close the request in
    case somebody out there decides they want to implement
    it. :-)

     
  • Logged In: YES
    user_id=327012

    When you run the javadoc tool, I believe these files are
    automatically created.