COSC-052: Computer Science II

Homework 2
Spring 2023

Due: F 2/17 @ 5 PM
3 points

This homework is to give you some practice writing documentation (doc) comments and using doxygen to generate documentation from those doc comments. By default, doxygen produces documentation in two formats: HTML and LaTeX (pronounced 'lay-TEK'). HTML is the hyper-text markup language, which one uses for writing Web pages. LaTeX is a typesetting program widely used to produce technical publications. After producing documentation in these formats, as an optional exercise, you can generate a PDF file using the documentation in LaTeX and publish a Web page using the documentation in HTML.

Note that in order to complete this homework you need to fix any problems with your doc comments. When you run doxygen on your source code, it prints error messages for the problems it finds.

I have created a few screencast on using doc comments to document classes and methods:

The classes store and manipulate information about individual playing cards, a deck of cards, and a hand of cards. There are also routines for calculating the value of a hand for Blackjack.

Running doxygen

Log on to cs-class-1 and copy and unzip the file for this homework by typing:
cs-class-1% cp ~maloofm/cosc052/hw2.zip ./
cs-class-1% unzip hw2.zip
Archive:  hw2.zip
  inflating: hw2/deck.cpp
  inflating: hw2/hand.h
  inflating: hw2/card.h
  inflating: hw2/main.cpp
  inflating: hw2/deck.h
  inflating: hw2/Makefile.dep
  inflating: hw2/main.h
  inflating: hw2/hand.cpp
  inflating: hw2/Makefile
  inflating: hw2/card.cpp
cs-class-1% rm hw2.zip
cs-class-1% cd hw2
In the hw2 directory you'll see classes for storing and manipulating information about a deck of playing cards and for drawing hands from a deck of cards. You can compile the project using the Makefile. The main function draws a hand of five random cards from the deck, prints the hand to the console, and prints its value.

In the .h files, write class and data member documentation comments. In the .cpp files, write method documentation comments. You do not need to document the main function. Use tags @author, @version, @param, @return, and @throws, where appropriate.

To run doxygen on the source in the directory, type

cs-class-1% cd hw2
cs-class-1% doxygen -g
cs-class-1% doxygen
The first command generates a configuration file named Doxyfile. The second command grabs and processes the doc comments present in all of your .h and .cpp files. You can also type 'make docs'.

You should see an obscene amount of output, but eventually you should return to the cs-class-1 prompt. After listing the contents of the directory, you should see two new directories: html and latex. When you get to this point, you can type 'make clean' and then 'make submit' to produce the file submit.zip that you can upload to Autolab.

In its default setting, doxygen does not generate documentation for private data members and methods, since programmers using classes under normal circumstances can't access those elements. Of course programmers who are implementing classes using generated documentation will need to see the comments for private data members and methods. And for this homework you do need to document private elements.

It is not requied, but if you want to generate documentation for private data members and methods, you can open the file Doxyfile and search for EXTRACT. You should see

  ...
  EXTRACT_ALL            = NO

  # If the EXTRACT_PRIVATE tag is set to YES all private members of a class
  # will be included in the documentation.

  EXTRACT_PRIVATE        = NO
  ...
If you change NO to YES on both of those lines and rerun doxygen (not doxygen -g), then doxygen will generate documentation for the private data members and methods.

Before submitting be sure to include the honor statement. In a file named HONOR, include the following statement with the appropriate modifications:

In accordance with the class policies and Georgetown's Honor System,
I certify that, with the exceptions of the class resources and those
items noted below, I have neither given nor received any assistance
on this project.

Name
NetID

As optional exercises, you can generate PDF documentation, HTML documentation, or both. For each of these, a transcript of my session appears below.

Optional: Generating PDF Documentation

To generate a PDF file from the documentation in LaTeX, change into the latex directory and list its contents:
cs-class-1% cd latex
cs-class-1% ls
You'll see a bunch of files, but you should see your friend, the Makefile.

Be bold and type 'make'. You will again see an obscene amount of output, but when it stops, again list the contents of the directory. You should see a number of files with the root 'refman', which is an abbreviation for reference manual. There should be a file named refman.pdf. You can transfer that file to your laptop and view it like any other PDF file.

The following is a transcript of my session. Bold type denotes commands I typed.

cs-class-1% cd hw2
cs-class-1% ls
card.cpp  deck.cpp  hand.cpp  main.cpp  Makefile
card.h    deck.h    hand.h    main.h  Makefile.dep
cs-class-1% doxygen -g
cs-class-1% doxygen
Searching for include files...
Searching for example files...
...
Generating example index...
Generating file member index...
cs-class-1% ls
card.cpp  deck.cpp  hand.cpp  html/   main.cpp  Makefile
card.h    deck.h    hand.h    latex/  main.h  Makefile.dep
cs-class-1% cd latex
cs-class-1% ls
annotated.tex  classDeck.tex  doxygen.sty  refman.tex
classCard.tex  classHand.tex  Makefile
cs-class-1% make
rm -f *.ps *.dvi *.aux *.toc *.idx *.ind *.ilg *.log *.out refman.pdf
pdflatex refman.tex
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
...
Output written on refman.pdf (14 pages, 118435 bytes).
Transcript written on refman.log.
latex_count=5 ; \
  while egrep -s 'Rerun (LaTeX|to get cross-references right)' refman.log && [ $latex_count -gt 0 ] ;\
    do \
      echo "Rerunning latex...." ;\
      pdflatex refman.tex ;\
      latex_count=`expr $latex_count - 1` ;\
    done
cs-class-1% ls
annotated.tex  classDeck.tex  doxygen.sty  refman.idx  refman.log  refman.tex
classCard.tex  classHand.aux  Makefile     refman.ilg  refman.out  refman.toc
classDeck.aux  classHand.tex  refman.aux   refman.ind  refman.pdf
cs-class-1% ls refman.pdf
refman.pdf
cs-class-1%

Optional: Publishing HTML Documentation

Publishing your documentation as a Web page is a little more involved because your account is not yet configured to display Web pages. The tricky thing is you have to change the permissions of the directories in your account so the Web server (and other people) can access the files for your Web site, but none of your other files. If you feel the least bit uncomfortable about this, please stop by and I'll help you.

Log on to cs-class-1.

The first step is to open two directories to the Web server. Unix has three types of privileges: u for user privilege, g for group privilege, and o for other privilege. For files and directories, each type has three permissions: r is for read permission, w is for write permission, and x is for execute permission.

If you do a long listing of the files in your directory by typing 'ls -l' at the prompt, the string in the first column of the listing shows the privileges of the files and directories (e.g, -rw-rw----). There are 10 positions. The first position indicates whether the file is a directory. Normal files have a hyphen in the first position; directories have a 'd'. The next nine positions show the read, write, and execute access for users, groups, and others, respectively. There are three types and three permissions for each type.

To set file and directory privileges, we use the chmod command, which changes the mode of files and directories.

To specify the mode for directories and files, we use a string that consists of references, an operator, and modes. References designate the type: u for user, g for group, o for other, and a for all. An operator is either +, which adds permissions, or -, which removes permissions. Finally, the modes are the permissions: r is for read, w is for write, and x is for execute. X sets execute privilege for directories, but not files. (We call also use three octal digits where each digit corresponds to user, group, and other, and each digit's bits correspond to read, write, and execute.)

As an example, if we wanted to give everyone execute privilege to the directory test, we would write 'chmod a+x test'. If we wanted to turn off all group and other privileges for all files in a directory, then we would write 'chmod go-rwx *'.

To set the privileges for your home directory, type:

cs-class-1% cd                                       <-- Takes you to your home directory
cs-class-1% cd ..                                    <-- Moves up to the parent directory
cs-class-1% chmod o+rx <your-netid>                  <-- Adds read and execute permission for other
cs-class-1% ls -l | grep <your-netid>                <-- Lists the files and searches (greps) for your netid
drwxr-xr-x  20 <your-netid> <your-netid> 4096 Feb  9 14:57 <your-netid>/
If you don't see the the permissions string drwxr-xr-x, then something didn't work, and you should come see me before proceeding.

The next step is to create the directory for your Web pages. By default, the Web server on cs-class-1 always serves pages from the user directory public_html. Once created, you'll need to set the correct permissions, which must be read and execute for others. To do this, type the following:

cs-class-1% cd                                       <-- Takes you to your home directory
cs-class-1% mkdir public_html                        <-- Makes the directory public_html
cs-class-1% chmod o+rx public_html                   <-- Adds read and execute permission for other
To test that you've configured your Web directory correctly, descend into the public_html directory, copy the simple Web page from my cosc052 directory, and set the file's permissions so others have read permission:
cs-class-1% cd public_html                           <-- Descends into public_html
cs-class-1% cp ~maloofm/cosc052/index.html ./        <-- Copies the Web page into the current directory
cs-class-1% chmod o+r index.html                     <-- Adds read permission for other
cs-class-1% ls -l index.html                         <-- Displays the long listing of the file
-rw-r--r--  1 <your-netid> <your-netid> 37 Jan 18 22:12 index.html
Next, go to your favorite Web browser, and see if cs-class-1 will serve you the page. Type the following URL with the appropriate substitution into the address bar:
http://cs-class-1.uis.georgetown.edu/~<your-netid>
The string "Hello!" should appear in your browser, along with a dead link to "HW2 Documentation." If this doesn't work, guess what? Come see me.

The next step is to make a directory for your documentation, copy it from your hw2 directory, and set the proper file and directory permissions. Use pwd to make sure you're in the public_html directory. If you are not, then type:

cs-class-1% cd
cs-class-1% cd public_html
Once in the public_html directory, type
cs-class-1% mkdir hw2docs                             <-- Makes a directory named hw2docs
cs-class-1% cd hw2docs                                <-- Descends into the directory hw2docs
cs-class-1% cp -r ~/hw2/html/* ./                     <-- Copies recursively the contents of hw2/html to the current directory
cs-class-1% cd ..                                     <-- Moves up to the directory public_html
cs-class-1% chmod -R o+rX hw2docs                     <-- Adds read and execute permissions recursively for other for the directory hw2docs
Assuming that your documentation is in the directory $HOME/hw2/html, you should be able to use your browser to click the link to "HW2 Documentation". Click around and check it out.

N.B. At this point, the directory public_html is a public directory, so do not put anything in that directory that you don't want everyone on the Internet to access. After completing this step, if you want to take down your Web pages, you can change the permissions of the files and directories:

cs-class-1% cd                                       <-- Takes you to your home directory
cs-class-1% chmod -R o-rx public_html                <-- Recursively removes read and execute privilege for other for public_html and all files and directories therein
If you want to completely remove these directories and files, type the rather dangerous command:
cs-class-1% cd                                       <-- Takes you to your home directory
cs-class-1% rm -r public_html                        <-- Recursively removes public_html and all therein

A transcript of my session follows:

cs-class-1% cd
cs-class-1% cd ..
cs-class-1% chmod o+rx maloofm
cs-class-1% ls -l | grep maloofm
drwxr-xr-x  19 maloofm  maloofm     4096 Feb  9 16:09 maloofm/
cs-class-1% cd
cs-class-1% mkdir public_html
cs-class-1% chmod o+rx public_html
cs-class-1% cd public_html
cs-class-1% cp ~maloofm/cosc052/index.html ./
cs-class-1% ls -l index.html
-rw-rw----  1 maloofm maloofm 103 Feb  9 16:11 index.html
cs-class-1% chmod o+r index.html
cs-class-1% ls -l index.html
-rw-rw-r--  1 maloofm maloofm 103 Feb  9 16:11 index.html
cs-class-1% pwd
/home/maloofm/public_html
cs-class-1% mkdir hw2docs
cs-class-1% ls
index.html  hw2docs/
cs-class-1% cd hw2docs
cs-class-1% cp -r ~/hw2/html/* ./
cs-class-1% ls
annotated.html          classHand.html          functions.html       tab_b.gif
card_8h_source.html     classHand-members.html  functions_vars.html  tab_l.gif
classCard.html          deck_8h_source.html     hand_8h_source.html  tab_r.gif
classCard-members.html  doxygen.css             index.html           tabs.css
classDeck.html          doxygen.png             installdox*
classDeck-members.html  files.html              main_8h_source.html
classes.html            functions_func.html     search/
cs-class-1% cd ..
cs-class-1% chmod -R o+rX hw2docs
cs-class-1%

Copyright © 2023 Mark Maloof. All Rights Reserved. This material may not be published, broadcast, rewritten, or redistributed.